serega 0.20.1 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11094f59dcd5d1d918604998ac267dbd13297bf0f70a9f3da5fd5ba74eb76b06
-  data.tar.gz: 97d1a419769b73937afde735e24210690e2f7702943d60db5be4252301e07255
+  metadata.gz: e72fdcef5f9baae349a3eae9c55029ef979cffdaabb5ab74e2f5228acaf93cf5
+  data.tar.gz: ef9375aa580c68856c78a016fc3dfcfef49f534d00c96af4deb4cbce20d9ce84
 SHA512:
-  metadata.gz: f9e3bfb207894f09c9c88658bad62e2a28e8b4d44648a74f807d332862b0cd7bdc67870f0d06786de0eb64537fd1a824c5d4f375406b71d18410b63c5a8c5320
-  data.tar.gz: 1171f2aabb7ce1c63a9e2f95f5413e9d80a882326ada4fac561b527c8a1adcc263ff19d6224eb070f0ebb333254ff48c9c7f56861ff6418732848cde3ffbc5b5
+  metadata.gz: 8ee1f484b9b1b66ada9570086f687c74f2b833c302e4685946d3787d6bce92e06d670e4ef0eae23a13c6c4c5090cc025c3bd73f5ea03c002c5bdcaffb2377238
+  data.tar.gz: 43ef3d1bbc6b2dd209674d237287ae68efead6e17bfc9ea1d67b8957998d7fb8f346119f8e12c7469e5d26a1f9bda099f507506ca32a2b08eed611c529105dd1

data/README.md

@@ -1,10 +1,10 @@
+# Serega Ruby Serializer
+
 [![Gem Version](https://badge.fury.io/rb/serega.svg)](https://badge.fury.io/rb/serega)
 [![GitHub Actions](https://github.com/aglushkov/serega/actions/workflows/main.yml/badge.svg?event=push)](https://github.com/aglushkov/serega/actions/workflows/main.yml)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/f10c0659e16e25e49faa/test_coverage)](https://codeclimate.com/github/aglushkov/serega/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/f10c0659e16e25e49faa/maintainability)](https://codeclimate.com/github/aglushkov/serega/maintainability)
 
-# Serega Ruby Serializer
-
 The Serega Ruby Serializer provides easy and powerful DSL to describe your
 objects and serialize them to Hash or JSON.
 
@@ -18,14 +18,14 @@ It has some great features:
 
 - Manually [select serialized fields](#selecting-fields)
 - Secure from malicious queries with [depth_limit][depth_limit] plugin
-- Solutions for N+1 problem (via [batch][batch], [preloads][preloads] or
-  [activerecord_preloads][activerecord_preloads] plugins)
+- Solutions for N+1 problem (via built-in [batch loading](#batch-loading), [preloads][preloads] or
+  [activerecord_preloads][activerecord_preloads] plugin)
 - Built-in object presenter ([presenter][presenter] plugin)
 - Adding custom metadata (via [metadata][metadata] or
   [context_metadata][context_metadata] plugins)
 - Value formatters ([formatters][formatters] plugin) helps to transform
-  time, date, money, percentage, and any other values in the same way keeping
-  the code dry
+  time, date, money, percentage, and any other values in the same way
+  keeping the code dry
 - Conditional attributes - ([if][if] plugin)
 - Auto camelCase keys - [camel_case][camel_case] plugin
 
@@ -63,19 +63,28 @@ end
 
 ### Adding attributes
 
+⚠️ Attribute names are checked to include only "a-z", "A-Z", "0-9", "\_", "-",
+"~" characters.
+
+We allow ONLY these characters as we want to be able to use attribute names in
+URLs without escaping.
+
+This rule can be turned off with simple config option: `config.check_attribute_name = false`
+
 ```ruby
 class UserSerializer < Serega
   # Regular attribute
   attribute :first_name
 
-  # Option :method specifies the method that must be called on the serialized object
+  # Option :method specifies the method that must be called on the
+  # serialized object
   attribute :first_name, method: :old_first_name
 
   # Block is used to define attribute value
   attribute(:first_name) { |user| user.profile&.first_name }
 
-  # Option :value can be used with a Proc or callable object to define attribute
-  # value
+  # Option :value can be used with a Proc or callable object to define
+  # attribute value
   attribute :first_name, value: UserProfile.new # must have #call method
   attribute :first_name, value: proc { |user| user.profile&.first_name }
 
@@ -106,12 +115,13 @@ class UserSerializer < Serega
   attribute :posts, serializer: -> { PostSerializer }
 
   # Option `:many` specifies a has_many relationship. It is optional.
-  # If not specified, it is defined during serialization by checking `object.is_a?(Enumerable)`
+  # If not specified, it is defined during serialization by checking
+  # `object.is_a?(Enumerable)`
   # Also the `:many` changes the default value from `nil` to `[]`.
   attribute :posts, serializer: PostSerializer, many: true
 
-  # Option `:preload` can be specified when enabled `:preloads` plugin
-  # It allows to specify associations to preload to attribute value
+  # Option `:preload` allows to specify associations to preload to
+  # attribute value
   attribute(:email, preload: :emails) { |user| user.emails.find(&:verified?) }
 
   # Options `:if, :unless, :if_value and :unless_value` can be specified
@@ -131,26 +141,6 @@ class UserSerializer < Serega
 end
 ```
 
----
-
-⚠️ Attribute names are checked to include only "a-z", "A-Z", "0-9", "\_", "-",
-"~" characters.
-
-We allow ONLY these characters as we want to be able to use attribute names in
-URLs without escaping.
-
-The check can be turned off:
-
-```ruby
-# Disable globally
-Serega.config.check_attribute_name = false
-
-# Disable for specific serializer
-class SomeSerializer < Serega
-  config.check_attribute_name = false
-end
-```
-
 ### Serializing
 
 We can serialize objects using class methods `.to_h`, `.to_json`, `.as_json` and
@@ -216,7 +206,7 @@ Modifiers can be provided as Hash, Array, String, Symbol, or their combinations.
 
 With plugin [string_modifiers][string_modifiers] we can provide modifiers as
 single `String` with attributes split by comma `,` and nested values inside
-brackets `()`, like: `username,enemies(username,email)`. This can be very useful
+brackets `()`, like: `first_name,last_name,addresses(line1,line2)`. This can be very useful
 to accept the list of fields in **GET** requests.
 
 When a non-existing attribute is provided, the `Serega::AttributeNotExist` error
@@ -332,6 +322,67 @@ UserSerializer.new.to_h(user, context: {current_user: user}) # same
 # => {:email=>"email@example.com"}
 ```
 
+### Batch Loading
+
+Serega includes built-in batch loading functionality to efficiently load data on demand and solve N+1 problems.
+
+#### Defining Named Batch Loaders
+
+Named loaders can be defined using the `batch_loader` class method and reused across attributes:
+
+```ruby
+class UserSerializer < Serega
+  # Define named loaders
+  batch_loader :comments_count, ->(users) { Comment.where(user: users).group(:user_id).count }
+  batch_loader :comments_count, CommentsCountLoader # Example with callable class
+
+  # Full attribute example
+  attribute :comments_count, batch: { use: :comments_count },
+    value: proc { |user, batch:| batch[:comments_count][user.id] }
+
+  # Shorter version
+  attribute :comments_count, batch: { use: :comments_count, id: :id } # Equivalent, id: :id is default
+
+  # Shortest version
+  attribute :comments_count, batch: true # Equivalent
+end
+```
+
+#### Using Custom Loaders
+
+Custom loaders can be provided directly using the `:use` option with any callable object:
+
+```ruby
+class UserSerializer < Serega
+  # Inline proc loader
+  attribute :followers_count,
+    batch: { use: ->(users) { Follow.where(user: users).group(:user_id).count } }
+
+  # Callable class loader
+  attribute :likes_count, batch: { use: LikesCountLoader }
+
+  # Method reference
+  attribute :views_count, batch: { use: ViewsCounter.method(:batch_load) }
+end
+```
+
+#### Using Multiple Loaders in Same Attribute
+
+Custom loaders can be provided directly using the `:use` option with any callable object:
+
+```ruby
+class UserSerializer < Serega
+  # Define named loaders
+  batch_loader :facebook_likes, FacebookLikesLoader
+  batch_loader :twitter_likes, TwitterLikesLoader
+
+  # Summarize likes
+  attribute :likes_count,
+    batch: { use: [:facebook_likes, :twitter_likes] },
+    value: { |user, batch:| batch[:facebook_likes][user.id] + batch[:twitter_likes][user.id] }
+end
+```
+
 ## Configuration
 
 Here are the default options. Other options can be added with plugins.
@@ -362,21 +413,20 @@ class AppSerializer < Serega
 end
 ```
 
-## Plugins
+## Preloads
 
-### Plugin :preloads
+Serega includes built-in preloads functionality that allows you to define
+`:preloads` to attributes and then merge preloads from serialized attributes
+into a single associations hash.
 
-Allows to define `:preloads` to attributes and then allows to merge preloads
-from serialized attributes and return single associations hash.
+Configuration options:
 
-Plugin accepts options:
+- `config.auto_preload_attributes_with_delegate` - default `false`
+- `config.auto_preload_attributes_with_serializer` - default `false`
+- `config.auto_hide_attributes_with_preload` - default `false`
 
-- `auto_preload_attributes_with_delegate` - default `false`
-- `auto_preload_attributes_with_serializer` - default `false`
-- `auto_hide_attributes_with_preload` - default `false`
-
-These options are extremely useful if you want to forget about finding preloads
-manually.
+These options are extremely useful if you want to forget about finding
+preloads manually.
 
 Preloads can be disabled with the `preload: false` attribute option.
 Automatically added preloads can be overwritten with the manually specified
@@ -386,10 +436,9 @@ For some examples, **please read the comments in the code below**
 
 ```ruby
 class AppSerializer < Serega
-  plugin :preloads,
-    auto_preload_attributes_with_delegate: true,
-    auto_preload_attributes_with_serializer: true,
-    auto_hide_attributes_with_preload: true
+  config.auto_preload_attributes_with_delegate = true
+  config.auto_preload_attributes_with_serializer = true
+  config.auto_hide_attributes_with_preload = true
 end
 
 class UserSerializer < AppSerializer
@@ -432,7 +481,7 @@ UserSerializer.new(
 
 ---
 
-#### SPECIFIC CASE #1: Serializing the same object in association
+### SPECIFIC CASE #1: Serializing the same object in association
 
 For example, you show your current user as "user" and use the same user object
 to serialize "user_stats". `UserStatSerializer` relies on user fields and any
@@ -456,7 +505,7 @@ class UserSerializer < AppSerializer
 end
 ```
 
-#### SPECIFIC CASE #2: Serializing multiple associations as a single relation
+### SPECIFIC CASE #2: Serializing multiple associations as a single relation
 
 For example, "user" has two relations - "new_profile" and "old_profile". Also
 profiles have the "avatar" association. And you decided to serialize profiles in
@@ -490,7 +539,7 @@ UserSerializer.new.preloads
 # => {:new_profile=>{:avatar=>{}}, :old_profile=>{:avatar=>{}}}
 ```
 
-#### SPECIFIC CASE #3: Preload association through another association
+### SPECIFIC CASE #3: Preload association through another association
 
 ```ruby
 attribute :image,
@@ -501,34 +550,32 @@ attribute :image,
 ```
 
 In this case, we don't know if preloads defined in ImageSerializer, should be
-preloaded to `attachment` or `blob`, so please specify `preload_path` manually.
+preloaded to `attachment` or `blob`, so `preload_path` must be specified manually.
 You can specify `preload_path: nil` if you are sure that there are no preloads
 inside ImageSerializer.
 
 ---
 
-📌 Plugin `:preloads` only allows to group preloads together in single Hash, but
-they should be preloaded manually.
+📌 The built-in preloads functionality only allows to group preloads together
+in single Hash, but they should be preloaded manually.
 
-There are only [activerecord_preloads][activerecord_preloads] plugin that can
-be used to preload these associations automatically.
+There is the [activerecord_preloads][activerecord_preloads] plugin that can be used to preload these associations automatically.
 
-### Plugin :activerecord_preloads
+## Plugins
 
-(depends on [preloads][preloads] plugin, that must be loaded first)
+### Plugin :activerecord_preloads
 
 Automatically preloads associations to serialized objects.
 
 It takes all defined preloads from serialized attributes (including attributes
-from serialized relations), merges them into a single associations hash, and then
+from serialized associations), merges them into a single associations hash, and then
 uses ActiveRecord::Associations::Preloader to preload associations to objects.
 
 ```ruby
 class AppSerializer < Serega
-  plugin :preloads,
-    auto_preload_attributes_with_delegate: true,
-    auto_preload_attributes_with_serializer: true,
-    auto_hide_attributes_with_preload: false
+  config.auto_preload_attributes_with_delegate = true
+  config.auto_preload_attributes_with_serializer = true
+  config.auto_hide_attributes_with_preload = false
 
   plugin :activerecord_preloads
 end
@@ -549,167 +596,7 @@ UserSerializer.to_h(user)
 # => preloads {users_stats: {}, albums: { downloads: {} }}
 ```
 
-### Plugin :batch
-
-Helps to omit N+1.
-
-User must specify how attribute values are loaded -
-`attribute :foo, batch: {loader: SomeLoader, id_method: :id}`.
-
-The result must be returned as Hash, where each key is one of the provided IDs.
-
-```ruby
-class AppSerializer
-  plugin :batch
-end
-
-class UserSerializer < AppSerializer
-  attribute :comments_count,
-    batch: { loader: SomeLoader, id_method: :id }
-
-  attribute :company,
-    batch: { loader: SomeLoader, id_method: :id },
-    serializer: CompanySerializer
-end
-```
-
-#### Option :loader
-
-Loaders can be defined as a Proc, a callable value, or a named Symbol
-Named loaders should be predefined with
-`config.batch.define(:loader_name) { |ids| ... })`
-
-The loader can accept 1 to 3 arguments:
-
-1. List of IDs (each ID will be found by using the `:id_method` option)
-1. Context
-1. PlanPoint - a special object containing information about current
-   attribute and all children and parent attributes. It can be used to preload
-   required associations to batch values.
-   See [example](examples/batch_loader.rb) how
-   to find required preloads when using the `:preloads` plugin.
-
-```ruby
-class AppSerializer < Serega
-  plugin :batch, id_method: :id
-end
-
-class UserSerializer < Serega
-  # Define loader as a callable object
-  attribute :comments_count,
-    batch: { loader: CountLoader }
-
-  # Define loader as a Proc
-  attribute :comments_count,
-    batch: { loader: proc { |ids| CountLoader.call(ids) } }
-
-  # Define loader as a Symbol
-  config.batch.define(:comments_count_loader) { |ids| CountLoader.call(ids }
-  attribute :comments_count, batch: { loader: :comments_count_loader }
-end
-
-class CountLoader
-  def self.call(user_ids)
-    Comment.where(user_id: user_ids).group(:user_id).count
-  end
-end
-```
-
-#### Option :id_method
-
-The `:batch` plugin can be added with the global `:id_method` option. It can be
-a Symbol, Proc or any callable value that can accept the current object and
-context.
-
-```ruby
-class SomeSerializer
-  plugin :batch, id_method: :id
-end
-
-class UserSerializer < AppSerializer
-  attribute :comments_count,
-    batch: { loader: CommentsCountBatchLoader } # no :id_method here anymore
-
-  attribute :company,
-    batch: { loader: UserCompanyBatchLoader }, # no :id_method here anymore
-    serializer: CompanySerializer
-end
-
-```
-
-However, the global `id_method` option can be overwritten via
-`config.batch.id_method=` method or in specific attributes with the `id_method`
-option.
-
-```ruby
-class SomeSerializer
-  plugin :batch, id_method: :id # global id_method is `:id`
-end
-
-class UserSerializer < AppSerializer
-  # :user_id will be used as default `id_method` for all batch attributes
-  config.batch.id_method = :user_id
-
-  # id_method is :user_id
-  attribute :comments_count,
-    batch: { loader: CommentsCountBatchLoader }
-
-
-  # id_method is :user_id
-  attribute :company,
-    batch: { loader: UserCompanyBatchLoader }, serializer: CompanySerializer
-
-  # id_method is :uuid
-  attribute :points_amount,
-    batch: { loader: PointsBatchLoader, id_method: :uuid }
-end
-```
-
-#### Default value
-
-The default value for attributes without found value can be specified via
-`:default` option. By default, attributes without found value will be
-serialized as a `nil` value. Attributes marked as `many: true` will be
-serialized as empty array `[]` values.
-
-```ruby
-class UserSerializer < AppSerializer
-  # Missing values become empty arrays, as the `many: true` option is specified
-  attribute :companies,
-    batch: {loader: proc {}},
-    serializer: CompanySerializer,
-    many: true
-
-  # Missing values become `0` as specified directly
-  attribute :points_amount, batch: { loader: proc {} }, default: 0
-end
-```
-
-Batch attributes can be marked as hidden by default if the plugin is enabled
-with the `auto_hide` option. The `auto_hide` option can be changed with
-the `config.batch.auto_hide=` method.
-
-Look at [select serialized fields](#selecting-fields) for more information
-about hiding/showing attributes.
-
-```ruby
-class AppSerializer
-  plugin :batch, auto_hide: true
-end
-
-class UserSerializer < AppSerializer
-  config.batch.auto_hide = false
-end
-```
-
----
-⚠️ ATTENTION: The `:batch` plugin must be added to all serializers that have
-`:batch` attributes inside nested serializers. For example, when you serialize
-the `User -> Album -> Song` and the Song has a `batch` attribute, then
-the `:batch` plugin must be added to the User serializer.
-
-The best way would be to create one parent `AppSerializer < Serega` serializer
-and add the `:batch` plugin once to this parent serializer.
+For testing purposes preloading can be done manually with `#preload_associations_to(obj)` instance method
 
 ### Plugin :root
 
@@ -1101,13 +988,13 @@ Bug reports, pull requests and improvements ideas are very welcome!
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 [activerecord_preloads]: #plugin-activerecord_preloads
-[batch]: #plugin-batch
+[batch-loading]: #batch-loading
 [camel_case]: #plugin-camel_case
 [context_metadata]: #plugin-context_metadata
 [depth_limit]: #plugin-depth_limit
 [formatters]: #plugin-formatters
 [metadata]: #plugin-metadata
-[preloads]: #plugin-preloads
+[preloads]: #preloads
 [presenter]: #plugin-presenter
 [root]: #plugin-root
 [string_modifiers]: #plugin-string_modifiers

data/VERSION

@@ -1 +1 @@
-0.20.1
+0.30.0

data/lib/serega/attribute.rb

@@ -29,6 +29,18 @@ class Serega
       # @return [Boolean, nil] Attribute :hide option
       attr_reader :hide
 
+      # Attribute :preloads option
+      # @return [Hash, nil] Attribute :preloads option
+      attr_reader :preloads
+
+      # Attribute :preloads_path option
+      # @return [Array, nil] Attribute :preloads_path option
+      attr_reader :preloads_path
+
+      # Batch loader names required to detect attribute value
+      # @return [Array<Symbol>] Batch loader names
+      attr_reader :batch_loaders
+
       #
       # Initializes new attribute
       #
@@ -79,8 +91,20 @@ class Serega
       #
       # @return [Object] Serialized attribute value
       #
-      def value(object, context)
-        value_block.call(object, context)
+      def value(object, context, batches: nil)
+        # Signatires should match allowed signatures in CheckOptValue and CheckBlock
+        result =
+          case value_block_signature
+          when "1" then value_block.call(object)
+          when "1_ctx" then value_block.call(object, ctx: context)
+          when "1_batches" then value_block.call(object, batches: batches)
+          when "1_batches_ctx" then value_block.call(object, ctx: context, batches: batches)
+          when "2" then value_block.call(object, context)
+          when "2_batches_ctx" then value_block.call(object, context, ctx: context, batches: batches)
+          else value_block.call # signature is "0" - no parameters
+          end
+
+        result.nil? ? default : result
       end
 
       #
@@ -108,15 +132,19 @@ class Serega
 
       private
 
-      attr_reader :value_block
+      attr_reader :value_block, :value_block_signature
 
       def set_normalized_vars(normalizer)
         @name = normalizer.name
         @many = normalizer.many
         @default = normalizer.default
         @value_block = normalizer.value_block
+        @value_block_signature = normalizer.value_block_signature
         @hide = normalizer.hide
         @serializer = normalizer.serializer
+        @preloads = normalizer.preloads
+        @preloads_path = normalizer.preloads_path
+        @batch_loaders = normalizer.batch_loaders
       end
     end