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:



105
106
107
 
# File 'lib/serega.rb', line 105

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:



181
182
183
184
 
# File 'lib/serega.rb', line 181

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



156
157
158
 
# File 'lib/serega.rb', line 156

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:



214
215
216
217
218
219
 
# File 'lib/serega.rb', line 214

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



165
166
167
 
# File 'lib/serega.rb', line 165

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



267
268
269
270
271
272
 
# File 'lib/serega.rb', line 267

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:



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/serega.rb', line 114

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



141
142
143
144
145
146
147
148
149
 
# File 'lib/serega.rb', line 141

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:



240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/serega.rb', line 240

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)



288
289
290
291
292
293
 
# File 'lib/serega.rb', line 288

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