serega 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '001918eece6824f604d5bdd2a43321346d474355fd629759eaa894dabf94d7f4'
-  data.tar.gz: e68ee37be935e8c4a9bc2eca849a6d56b68feb56155519a612976cddd2013871
+  metadata.gz: 0f1dd539e1a0b60a167cb67c5e8bfb509d5ce3be4d8ce8151a97a5f646f53378
+  data.tar.gz: 39ed8e53b95cc192a0819fbc4452d2cb6951b9208566d0597802cd98b828669e
 SHA512:
-  metadata.gz: 4683bc9c753fbbcfc40c31e7a2833bddfe3a01711067a718ad9a01f263d8e7e576b768432e33dcaad688ddd2d3017e60ebfc3111d22a661d6f670ae465f9210c
-  data.tar.gz: ad5fd5c647484d9b68053e28a0e8a728e285727b7419e797cf89f73ea00abaf226c6c59d137afb7ba41b47fc1490b4948e11128d059257ed431da0574657998e
+  metadata.gz: 7b6519e8fb225d6bc132c5144b2268b8b7866e030a3c7a582febac6fc468a3cae449cf9298e05b5468c31c8a975629891e196ee0f1537cee401ceab394c573a2
+  data.tar.gz: bef92a58a8f730af6e97c3a36dbf6062aa7e3b99ad5c44484682447063018ec9dbcb345cc4715d1637a3d6c4c388f4b794a144b8250986db19efbe961b92c472

data/README.md

@@ -0,0 +1,650 @@
+[![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 to serialize them to Hash or JSON.
+
+---
+
+  📌 Serega does not depend on any gem and works with any framework
+
+---
+
+It has some great features:
+
+- Manually [select serialized fields](#selecting-fields)
+- Solutions for N+1 problem (via [batch][batch], [preloads][preloads] or [activerecord_preloads][activerecord_preloads] plugins)
+- Built-in object presenter ([presenter][presenter] plugin)
+- Adding custom metadata (via [metadata][metadata] or [context_metadata][context_metadata] plugins)
+- Attributes formatters ([formatters][formatters] plugin)
+
+## Installation
+
+`bundle add serega`
+
+
+### Define serializers
+
+Most apps should define **base serializer** with common plugins and settings to not repeat them in each serializer.
+Children serializers will inherit everything (plugins, config, attributes) from parent.
+
+```ruby
+class AppSerializer < Serega
+  # plugin :one
+  # plugin :two
+
+  # config.one = :one
+  # config.two = :two
+end
+
+class UserSerializer < AppSerializer
+  # attribute :one
+  # attribute :two
+end
+
+class CommentSerializer < AppSerializer
+  # attribute :one
+  # attribute :two
+end
+```
+
+### Adding attributes
+
+```ruby
+class UserSerializer < Serega
+  # Regular attribute
+  attribute :first_name
+
+  # Option :key specifies method in object
+  attribute :first_name, key: :old_first_name
+
+  # Block is used to define attribute value
+  attribute(:first_name) { |user| user.profile&.first_name }
+
+  # Option :value can be used with callable object to define attribute value
+  attribute :first_name, value: proc { |user| user.profile&.first_name }
+
+  # Option :delegate can be used to define attribute value. Sub-option :allow_nil by default is false
+  attribute :first_name, delegate: { to: :profile, allow_nil: true }
+
+  # Option :delegate can be used with :key sub-option to change method called on delegated object
+  attribute :first_name, delegate: { to: :profile, key: :fname }
+
+  # Option :const specifies attribute with specific constant value
+  attribute(:type, const: 'user')
+
+  # Option :hide specifies attributes that should not be serialized by default
+  attribute :tags, hide: true
+
+  # Option :serializer specifies nested serializer for attribute
+  # We can specify serializer as Class, String or Proc.
+  # Use String or Proc if you have cross references in serializers.
+  attribute :posts, serializer: PostSerializer
+  attribute :posts, serializer: "PostSerializer"
+  attribute :posts, serializer: -> { PostSerializer }
+
+  # Option `:many` specifies a has_many relationship
+  # Usually it is defined automatically by checking `is_a?(Enumerable)`
+  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
+  attribute :email, preload: :emails, value: proc { |user| user.emails.find(&:verified?) }
+
+  # Option `:hide_nil` can be specified when enabled `:hide_nil` plugin
+  # It is literally hides attribute if its value is nil
+  attribute :email, hide_nil: true
+
+  # Option `:format` can be specified when enabled `:formatters` plugin
+  # It changes attribute value
+  attribute :created_at, format: :iso_time
+  attribute :updated_at, format: :iso_time
+
+  # Option `:format` also can be used as Proc
+  attribute :created_at, format: proc { |time| time.strftime("%Y-%m-%d")}
+end
+```
+
+### Serializing
+
+We can serialize objects using class methods `.to_h`, `.to_json`, `.as_json` and same instance methods `#to_h`, `#to_json`, `#as_json`.
+`to_h` method is also aliased as `call`.
+
+
+```ruby
+user = OpenStruct.new(username: 'serega')
+
+class UserSerializer < Serega
+  attribute :username
+end
+
+UserSerializer.to_h(user) # => {username: "serega"}
+UserSerializer.to_h([user]) # => [{username: "serega"}]
+
+UserSerializer.to_json(user) # => '{"username":"serega"}'
+UserSerializer.to_json([user]) # => '[{"username":"serega"}]'
+
+UserSerializer.as_json(user) # => {"username":"serega"}
+UserSerializer.as_json([user]) # => [{"username":"serega"}]
+```
+
+---
+⚠️ When you serialize `Struct` object, specify manually `many: false`. As Struct is Enumerable and we check `object.is_a?(Enumerable)` to detect if we should return array.
+
+```ruby
+  UserSerializer.to_h(user_struct, many: false)
+```
+
+### Selecting Fields
+
+  By default all attributes are serialized (except marked as `hide: true`).
+
+  We can provide **modifiers** to select only needed attributes:
+
+  - *only* - lists attributes to serialize;
+  - *except* - lists attributes to not serialize;
+  - *with* - lists attributes to serialize additionally (By default all attributes are exposed and will be serialized, but some attributes can be hidden when they are defined with `hide: true` option, more on this below. `with` modifier can be used to expose such attributes).
+
+  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 to accept list of fields in **GET** requests.
+
+  When provided non-existing attribute, `Serega::AttributeNotExist` error will be raised. This error can be muted with `check_initiate_params: false` parameter.
+
+```ruby
+class UserSerializer < Serega
+  plugin :string_modifiers # to send all modifiers in one string
+
+  attribute :username
+  attribute :first_name
+  attribute :last_name
+  attribute :email, hide: true
+  attribute :enemies, serializer: UserSerializer, hide: true
+end
+
+joker = OpenStruct.new(username: 'The Joker', first_name: 'jack', last_name: 'Oswald White', email: 'joker@mail.com', enemies: [])
+bruce = OpenStruct.new(username: 'Batman', first_name: 'Bruce', last_name: 'Wayne', email: 'bruce@wayneenterprises.com', enemies: [])
+joker.enemies << bruce
+bruce.enemies << joker
+
+# Default
+UserSerializer.to_h(bruce) # => {:username=>"Batman", :first_name=>"Bruce", :last_name=>"Wayne"}
+
+# With `:only` modifier
+# Next 3 lines are identical:
+UserSerializer.to_h(bruce, only: [:username, { enemies: [:username, :email] }])
+UserSerializer.new(only: [:username, { enemies: [:username, :email] }]).to_h(bruce)
+UserSerializer.new(only: 'username,enemies(username,email)').to_h(bruce)
+# => {:username=>"Batman", :enemies=>[{:username=>"The Joker", :email=>"joker@mail.com"}]}
+
+# With `:except` modifier
+# Next 3 lines are identical:
+UserSerializer.new(except: %i[first_name last_name]).to_h(bruce)
+UserSerializer.to_h(bruce, except: %i[first_name last_name])
+UserSerializer.to_h(bruce, except: 'first_name,last_name')
+# => {:username=>"Batman"}
+
+# With `:with` modifier
+# Next 3 lines are identical:
+UserSerializer.new(with: %i[email enemies]).to_h(bruce)
+UserSerializer.to_h(bruce, with: %i[email enemies])
+UserSerializer.to_h(bruce, with: 'email,enemies')
+# => {:username=>"Batman", :first_name=>"Bruce", :last_name=>"Wayne", :email=>"bruce@wayneenterprises.com", :enemies=>[{:username=>"The Joker", :first_name=>"jack", :last_name=>"Oswald White"}]}
+
+# With not existing attribute
+# Next 3 lines are identical:
+UserSerializer.new(only: %i[first_name enemy]).to_h(bruce)
+UserSerializer.to_h(bruce, only: %i[first_name enemy])
+UserSerializer.to_h(bruce, only: 'first_name,enemy')
+# => raises Serega::AttributeNotExist, "Attribute 'enemy' not exists"
+
+# With not existing attribute and disabled validation
+# Next 3 lines are identical:
+UserSerializer.new(only: %i[first_name enemy], check_initiate_params: false).to_h(bruce)
+UserSerializer.to_h(bruce, only: %i[first_name enemy], check_initiate_params: false)
+UserSerializer.to_h(bruce, only: 'first_name,enemy', check_initiate_params: false)
+# => {:first_name=>"Bruce"}
+```
+
+### Using Context
+
+Sometimes you can decide to use some context during serialization, like current_user or any.
+
+```ruby
+class UserSerializer < Serega
+  attribute(:email) do |user, ctx|
+    user.email if ctx[:current_user] == user
+  end
+end
+
+user = OpenStruct.new(email: 'email@example.com')
+UserSerializer.(user, context: {current_user: user}) # => {:email=>"email@example.com"}
+UserSerializer.new.to_h(user, context: {current_user: user}) # same
+```
+
+## Configuration
+
+This is initial config options, other config options can be added by plugins
+
+```ruby
+class AppSerializer < Serega
+  # Configure adapter to serialize to JSON.
+  # It is `JSON.dump` by default. When Oj gem is loaded then default is `Oj.dump(data, mode: :compat)`
+  config.to_json = ->(data) { Oj.dump(data, mode: :compat) }
+
+  # Configure adapter to de-serialize JSON. De-serialization is used only for `#as_json` method.
+  # It is `JSON.parse` by default. When Oj gem is loaded then default is `Oj.load(data)`
+  config.from_json = ->(data) { Oj.load(data) }
+
+  # Disable/enable validation of modifiers params `:with`, `:except`, `:only`
+  # By default it is enabled. After disabling, when provided not existed attribute it will be just skipped.
+  config.check_initiate_params = false # default is true, enabled
+
+  # Stores in memory prepared `maps` of serialized attributes during serialization.
+  # Next time serialization happens with same modifiers (`:only, :except, :with`), we will use already prepared `map`.
+  # Setting defines storage size (count of stored `maps` with different modifiers).
+  config.max_cached_map_per_serializer_count = 50 # default is 0, disabled
+end
+```
+
+## Plugins
+
+### Plugin :preloads
+
+Allows to define `:preloads` to attributes and then allows to merge preloads
+from serialized attributes and return single associations hash.
+
+Plugin accepts options:
+- `auto_preload_attributes_with_delegate` - default `false`
+- `auto_preload_attributes_with_serializer` - default `false`
+- `auto_hide_attributes_with_preload` - default `false`
+
+This options are very handy if you want to forget about finding preloads manually.
+
+Preloads can be disabled with `preload: false` attribute option option.
+Also automatically added preloads can be overwritten with manually specified `preload: :another_value`.
+
+Some examples, **please read 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
+end
+
+class UserSerializer < AppSerializer
+  # No preloads
+  attribute :username
+
+  # Specify `preload: :user_stats` manually
+  attribute :followers_count, preload: :user_stats, value: proc { |user| user.user_stats.followers_count }
+
+  # Automatically `preloads: :user_stats` as `auto_preload_attributes_with_delegate` option is true
+  attribute :comments_count, delegate: { to: :user_stats }
+
+  # Automatically `preloads: :albums` as `auto_preload_attributes_with_serializer` option is true
+  attribute :albums, serializer: 'AlbumSerializer'
+end
+
+class AlbumSerializer < AppSerializer
+  attribute :images_count, delegate: { to: :album_stats }
+end
+
+# By default preloads are empty, as we specify `auto_hide_attributes_with_preload = true`,
+# and attributes with preloads will be not serialized
+UserSerializer.new.preloads # => {}
+UserSerializer.new.to_h(OpenStruct.new(username: 'foo')) # => {:username=>"foo"}
+
+UserSerializer.new(with: :followers_count).preloads # => {:user_stats=>{}}
+UserSerializer.new(with: %i[followers_count comments_count]).preloads # => {:user_stats=>{}}
+UserSerializer.new(with: [:followers_count, :comments_count, { albums: :images_count }]).preloads # => {:user_stats=>{}, :albums=>{:album_stats=>{}}}
+```
+
+---
+One tricky case, that you will probably never see in real life:
+
+Manually you can preload multiple associations, like this:
+
+```ruby
+attribute :image, serializer: ImageSerializer, preload: { attachment: :blob }, value: proc { |record| record.attachment }
+```
+
+In this case we mark last element (in this case it will be `blob`) as main,
+so nested associations, if any, will be preloaded to this `blob`.
+If you need to preload them to `attachment`,
+please specify additionally `:preload_path` option like this:
+
+```ruby
+attribute :image, serializer: ImageSerializer, preload: { attachment: :blob }, preload_path: %i[attachment], value: proc { |record| record.attachment }
+```
+---
+
+📌 Plugin `:preloads` only allows to group preloads together in single Hash, but they should be preloaded manually. For now there are only [activerecord_preloads][activerecord_preloads] plugin that can automatically preload associations.
+
+
+### Plugin :activerecord_preloads
+
+(depends on [preloads][preloads] plugin, that must be loaded first)
+
+Automatically preloads associations to serialized objects.
+
+It takes all defined preloads from serialized attributes (including attributes from serialized relations),
+merges them into single associations hash and then uses ActiveRecord::Associations::Preloader
+to preload associations to serialized 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
+
+  plugin :activerecord_preloads
+end
+
+class UserSerializer < AppSerializer
+  attribute :username
+  attribute :comments_count, delegate: { to: :user_stats }
+  attribute :albums, serializer: AlbumSerializer
+end
+
+class AlbumSerializer < AppSerializer
+  attribute :title
+  attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
+end
+
+UserSerializer.to_h(user) # => preloads {users_stats: {}, albums: { downloads: {} }}
+```
+
+### Plugin :batch
+
+Adds ability to load attributes values in batches.
+
+It can be used to omit N+1, to calculate counters for different objects in single query, to request any data from external storage.
+
+Added new `:batch` attribute option, example:
+```
+attribute :name, batch: { key: :id, loader: :name_loader, default: '' }
+```
+
+Attribute `:batch` option must be a hash with this keys:
+- `key` (required) [Symbol, Proc, callable] - Defines identifier of current object
+- `loader` (required) [Symbol, Proc, callable] - Defines how to fetch values for batch of keys. Accepts 3 parameters: keys, context, point.
+- `default` (optional) - Default value used when loader does not return value for current key. By default it is `nil` or `[]` when attribute has additional option `many: true` (ex: `attribute :name, many: true, batch: { ... }`).
+
+If `:loader` was defined using name (as Symbol) then batch loader must be defined using `config.batch_loaders.define(:loader_name) { ... }` method. Result of this block must be a Hash where keys are - provided keys, and values are - batch loaded values for according keys.
+
+Batch loader works well with [`activerecord_preloads`][activerecord_preloads] plugin.
+
+```ruby
+class PostSerializer < Serega
+  plugin :batch
+
+  # Define batch loader via callable class, it must accept three args (keys, context, nested_attributes)
+  attribute :comments_count, batch: { key: :id, loader: PostCommentsCountBatchLoader, default: 0}
+
+  # Define batch loader via Symbol, later we should define this loader via config.batch_loaders.define(:posts_comments_counter) { ... }
+  attribute :comments_count, batch: { key: :id, loader: :posts_comments_counter, default: 0}
+
+  # Define batch loader with serializer
+  attribute :comments, serializer: CommentSerializer, batch: { key: :id, loader: :posts_comments, default: []}
+
+  # Resulted block must return hash like { key => value(s) }
+  config.batch_loaders.define(:posts_comments_counter) do |keys|
+    Comment.group(:post_id).where(post_id: keys).count
+  end
+
+  # We can return objects that will be automatically serialized if attribute defined with :serializer
+  # Parameter `context` can be used when loading batch
+  # Parameter `point` can be used to find nested attributes  that will be serialized
+  config.batch_loaders.define(:posts_comments) do |keys, context, point|
+    # point.nested_points - if you need to manually check all nested attributes that will be serialized
+    # point.preloads - if you need to find nested preloads (works with :preloads plugin only)
+
+    Comment
+      .preload(point.preloads) # Can be skipped when used :activerecord_preloads plugin
+      .where(post_id: keys)
+      .where(is_spam: false)
+      .group_by(&:post_id)
+  end
+end
+```
+
+### Plugin :root
+
+Allows to add root key to your serialized data
+
+Accepts options:
+- :root - specifies root for all responses
+- :root_one - specifies root for single object serialization only
+- :root_many - specifies root for multiple objects serialization only
+
+Adds additional config options:
+- config.root.one
+- config.root.many
+- config.root.one=
+- config.root_many=
+
+Default root is `:data`.
+
+Root also can be changed per serialization.
+
+Also root can be removed for all responses by providing `root: nil`. In this case no root will be added to response, but
+you still can to add it per serialization
+
+```ruby
+ #@example Define plugin
+
+ class UserSerializer < Serega
+   plugin :root # default root is :data
+ end
+
+ class UserSerializer < Serega
+   plugin :root, root: :users
+ end
+
+ class UserSerializer < Serega
+   plugin :root, root_one: :user, root_many: :people
+ end
+
+ class UserSerializer < Serega
+   plugin :root, root: nil # no root by default
+ end
+```
+
+```ruby
+ # @example Change root per serialization:
+
+ class UserSerializer < Serega
+   plugin :root
+ end
+
+ UserSerializer.to_h(nil)              # => {:data=>nil}
+ UserSerializer.to_h(nil, root: :user) # => {:user=>nil}
+ UserSerializer.to_h(nil, root: nil)   # => nil
+```
+
+### Plugin :metadata
+
+Depends on: [`:root`][root] plugin, that must be loaded first
+
+Adds ability to describe metadata and adds it to serialized response
+
+Added class-level method `:meta_attribute`, to define metadata, it accepts:
+- *path [Array<Symbol>] - nested hash keys beginning from the root object.
+- **options [Hash] - defaults are `hide_nil: false, hide_empty: false`
+- &block [Proc] - describes value for current meta attribute
+
+```ruby
+class AppSerializer < Serega
+  plugin :root
+  plugin :metadata
+
+  meta_attribute(:version) { '1.2.3' }
+  meta_attribute(:ab_tests, :names) { %i[foo bar] }
+  meta_attribute(:meta, :paging, hide_nil: true) do |records, ctx|
+    next unless records.respond_to?(:total_count)
+
+    { page: records.page, per_page: records.per_page, total_count: records.total_count }
+  end
+end
+
+AppSerializer.to_h(nil) # => {:data=>nil, :version=>"1.2.3", :ab_tests=>{:names=>[:foo, :bar]}}
+```
+
+### Plugin :context_metadata
+
+Depends on: [`:root`][root] plugin, that must be loaded first
+
+Allows to provide metadata and attach it to serialized response.
+
+Accepts option `:context_metadata_key` with name of keyword that must be used to provide metadata. By default it is `:meta`
+
+Key can be changed in children serializers using config `config.context_metadata.key=(value)`
+
+```ruby
+class UserSerializer < Serega
+  plugin :root, root: :data
+  plugin :context_metadata, context_metadata_key: :meta
+
+  # Same:
+  # plugin :context_metadata
+  # config.context_metadata.key = :meta
+end
+
+UserSerializer.to_h(nil, meta: { version: '1.0.1' })
+# => {:data=>nil, :version=>"1.0.1"}
+```
+
+### Plugin :formatters
+
+Allows to define `formatters` and apply them on attributes.
+
+Config option `config.formatters.add` can be used to add formatters.
+
+Attribute option `:format` now can be used with name of formatter or with callable instance.
+
+```ruby
+class AppSerializer < Serega
+  plugin :formatters, formatters: {
+    iso8601: ->(value) { time.iso8601.round(6) },
+    on_off: ->(value) { value ? 'ON' : 'OFF' },
+    money: ->(value) { value.round(2) }
+  }
+end
+
+class UserSerializer < Serega
+  # Additionally we can add formatters via config in subclasses
+  config.formatters.add(
+    iso8601: ->(value) { time.iso8601.round(6) },
+    on_off: ->(value) { value ? 'ON' : 'OFF' },
+    money: ->(value) { value.round(2) }
+  )
+
+  # Using predefined formatter
+  attribute :commission, format: :money
+  attribute :is_logined, format: :on_off
+  attribute :created_at, format: :iso8601
+  attribute :updated_at, format: :iso8601
+
+  # Using `callable` formatter
+  attribute :score_percent, format: PercentFormmatter # callable class
+  attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
+end
+```
+
+### Plugin :presenter
+
+Helps to write clear code by adding attribute names as methods to Presenter
+
+```ruby
+class UserSerializer < Serega
+  plugin :presenter
+
+  attribute :name
+  attribute :address
+
+  class Presenter
+    def name
+      [first_name, last_name].compact_blank.join(' ')
+    end
+
+    def address
+      [country, city, address].join("\n")
+    end
+  end
+end
+```
+
+### Plugin :string_modifiers
+
+Allows to specify modifiers as strings.
+
+Serialized attributes must be split with `,` and nested attributes must be defined inside brackets `(`, `)`.
+
+Modifiers can still be provided old way with nested hashes or arrays.
+
+```ruby
+PostSerializer.plugin :string_modifiers
+PostSerializer.new(only: "id,user(id,username)").to_h(post)
+PostSerializer.new(except: "user(username,email)").to_h(post)
+PostSerializer.new(with: "user(email)").to_h(post)
+
+# Modifiers can still be provided old way with nested hashes or arrays.
+PostSerializer.new(with: {user: %i[email, username]}).to_h(post)
+```
+
+### Plugin :hide_nil
+
+Allows to hide attributes with `nil` values
+
+```ruby
+class UserSerializer < Serega
+  plugin :hide_nil
+
+  attribute :email, hide_nil: true
+end
+```
+
+## Errors
+
+- `Serega::SeregaError` is a base error raised by this gem.
+- `Serega::AttributeNotExist` error is raised when validating attributes in `:only, :except, :with` modifiers
+
+## Release
+
+To release a new version, read [RELEASE.md](https://github.com/aglushkov/serega/blob/master/RELEASE.md).
+
+## Development
+
+- `bundle install` - install dependencies
+- `bin/console` - open irb console with loaded gems
+- `bundle exec rspec` - run tests
+- `bundle exec rubocop` - check code standards
+- `yard stats --list-undoc --no-cache` - view undocumented code
+- `yard server --reload` - view code documentation
+
+## Contributing
+
+Bug reports, pull requests and improvements ideas are very welcome!
+
+## License
+
+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
+[context_metadata]: #plugin-context_metadata
+[formatters]: #plugin-formatters
+[metadata]: #plugin-metadata
+[preloads]: #plugin-preloads
+[presenter]: #plugin-presenter
+[root]: #plugin-root
+[string_modifiers]: #plugin-string_modifiers

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.8.1

data/lib/serega/attribute.rb

@@ -9,12 +9,15 @@ class Serega
     # Attribute instance methods
     #
     module AttributeInstanceMethods
+      # Returns attribute name
       # @return [Symbol] Attribute name
       attr_reader :name
 
+      # Returns attribute options
       # @return [Hash] Attribute options
       attr_reader :opts
 
+      # Returns attribute block
       # @return [Proc] Attribute originally added block
       attr_reader :block
 
@@ -40,26 +43,32 @@ class Serega
         @block = block
       end
 
-      # @return [Symbol] Object method name to will be used to get attribute value unless block provided
+      # Method name that will be used to get attribute value
+      #
+      # @return [Symbol] key
       def key
         @key ||= opts.key?(:key) ? opts[:key].to_sym : name
       end
 
-      # @return [Boolean, nil] Attribute initial :hide option value
+      # Shows current opts[:hide] option
+      # @return [Boolean, nil] Attribute :hide option value
       def hide
         opts[:hide]
       end
 
-      # @return [Boolean, nil] Attribute initialization :many option
+      # Shows current opts[:many] option
+      # @return [Boolean, nil] Attribute :many option value
       def many
         opts[:many]
       end
 
+      # Shows whether attribute has specified serializer
       # @return [Boolean] Checks if attribute is relationship (if :serializer option exists)
       def relation?
         !opts[:serializer].nil?
       end
 
+      # Shows specified serializer class
       # @return [Serega, nil] Attribute serializer if exists
       def serializer
         return @serializer if instance_variable_defined?(:@serializer)
@@ -73,6 +82,7 @@ class Serega
           end
       end
 
+      # Returns final block that will be used to find attribute value
       # @return [Proc] Proc to find attribute value
       def value_block
         return @value_block if instance_variable_defined?(:@value_block)
@@ -130,12 +140,13 @@ class Serega
       end
 
       def delegate_block
-        return unless opts.key?(:delegate)
+        delegate = opts[:delegate]
+        return unless delegate
 
-        key_method_name = key
-        delegate_to = opts[:delegate][:to]
+        key_method_name = delegate[:key] || key
+        delegate_to = delegate[:to]
 
-        if opts[:delegate][:allow_nil]
+        if delegate[:allow_nil]
           proc { |object| object.public_send(delegate_to)&.public_send(key_method_name) }
         else
           proc { |object| object.public_send(delegate_to).public_send(key_method_name) }

data/lib/serega/config.rb

@@ -8,6 +8,10 @@ class Serega
   #
   class SeregaConfig
     # :nocov: We can't use both :oj and :json adapters together
+
+    #
+    # Default config options
+    #
     DEFAULTS = {
       plugins: [],
       initiate_keys: %i[only with except check_initiate_params].freeze,
@@ -23,7 +27,9 @@ class Serega
     # SeregaConfig Instance methods
     module SeregaConfigInstanceMethods
       #
-      # @return [Hash] All config options
+      # Shows current config as Hash
+      #
+      # @return [Hash] config options
       #
       attr_reader :opts
 
@@ -37,31 +43,41 @@ class Serega
         @opts = SeregaUtils::EnumDeepDup.call(opts)
       end
 
+      #
+      # Shows used plugins
+      #
       # @return [Array] Used plugins
+      #
       def plugins
         opts.fetch(:plugins)
       end
 
-      # @return [Array<Symbol>] Allowed options keys for serializer initialization
+      # Returns options names allowed in `Serega#new` method
+      # @return [Array<Symbol>] allowed options keys
       def initiate_keys
         opts.fetch(:initiate_keys)
       end
 
+      # Returns options names allowed in `Serega.attribute` method
       # @return [Array<Symbol>] Allowed options keys for attribute initialization
       def attribute_keys
         opts.fetch(:attribute_keys)
       end
 
+      # Returns options names allowed in `to_h, to_json, as_json` methods
       # @return [Array<Symbol>] Allowed options keys for serialization
       def serialize_keys
         opts.fetch(:serialize_keys)
       end
 
+      # Returns :check_initiate_params config option
       # @return [Boolean] Current :check_initiate_params config option
       def check_initiate_params
         opts.fetch(:check_initiate_params)
       end
 
+      # Sets :check_initiate_params config option
+      #
       # @param value [Boolean] Set :check_initiate_params config option
       #
       # @return [Boolean] :check_initiate_params config option
@@ -70,11 +86,14 @@ class Serega
         opts[:check_initiate_params] = value
       end
 
+      # Returns :max_cached_map_per_serializer_count config option
       # @return [Boolean] Current :max_cached_map_per_serializer_count config option
       def max_cached_map_per_serializer_count
         opts.fetch(:max_cached_map_per_serializer_count)
       end
 
+      # Sets :max_cached_map_per_serializer_count config option
+      #
       # @param value [Boolean] Set :check_initiate_params config option
       #
       # @return [Boolean] New :max_cached_map_per_serializer_count config option
@@ -83,22 +102,26 @@ class Serega
         opts[:max_cached_map_per_serializer_count] = value
       end
 
+      # Returns current `to_json` adapter
       # @return [#call] Callable that used to construct JSON
       def to_json
         opts.fetch(:to_json)
       end
 
+      # Sets current `to_json` adapter
       # @param value [#call] Callable that used to construct JSON
       # @return [#call] Provided callable object
       def to_json=(value)
         opts[:to_json] = value
       end
 
+      # Returns current `from_json` adapter
       # @return [#call] Callable that used to parse JSON
       def from_json
         opts.fetch(:from_json)
       end
 
+      # Sets current `from_json` adapter
       # @param value [#call] Callable that used to parse JSON
       # @return [#call] Provided callable object
       def from_json=(value)

data/lib/serega/helpers/serializer_class_helper.rb

@@ -9,6 +9,7 @@ class Serega
     # Stores link to current serializer class
     #
     module SerializerClassHelper
+      # Shows serializer class current class is namespaced under
       # @return [Class<Serega>] Serializer class that current class is namespaced under.
       attr_accessor :serializer_class
     end

data/lib/serega/map_point.rb

@@ -11,9 +11,11 @@ class Serega
     module InstanceMethods
       extend Forwardable
 
+      # Shows current attribute
       # @return [Serega::SeregaAttribute] Current attribute
       attr_reader :attribute
 
+      # Shows nested points
       # @return [NilClass, Array<Serega::SeregaMapPoint>] Nested points or nil
       attr_reader :nested_points
 

data/lib/serega/plugins/activerecord_preloads/lib/preloader.rb

@@ -22,6 +22,8 @@ class Serega
             preload_handler.preload(object, preloads)
           end
 
+          # Returns handlers which will try to check if serialized object fits for preloading using this handler
+          #
           # @return [Array] Registered preload adapters for different types of initial records
           def handlers
             @handlers ||= [

data/lib/serega/plugins/batch/batch.rb

@@ -35,6 +35,7 @@ class Serega
     #   end
     #
     module Batch
+      # Returns plugin name
       # @return [Symbol] Plugin name
       def self.plugin_name
         :batch
@@ -159,6 +160,7 @@ class Serega
           @many = many
         end
 
+        # Returns proc that will be used to batch load registered keys values
         # @return [#call] batch loader
         def loader
           @batch_loader ||= begin
@@ -168,6 +170,7 @@ class Serega
           end
         end
 
+        # Returns proc that will be used to find batch_key for current attribute.
         # @return [Object] key (uid) of batch loaded object
         def key
           @batch_key ||= begin
@@ -176,6 +179,7 @@ class Serega
           end
         end
 
+        # Returns default value to use if batch loader does not return value for some key
         # @return [Object] default value for missing key
         def default_value
           if opts.key?(:default)
@@ -192,6 +196,8 @@ class Serega
       # @see Serega::SeregaConfig
       #
       module ConfigInstanceMethods
+        #
+        # Returns all batch loaders registered for current serializer
         #
         # @return [Serega::SeregaPlugins::Batch::BatchLoadersConfig] configuration for batch loaders
         #
@@ -253,11 +259,13 @@ class Serega
       #
       # Serega::SeregaMapPoint additional/patched class methods
       #
-      # @see Serega::SeregaAttribute
+      # @see SeregaAttribute
       #
       module MapPointInstanceMethods
         #
-        # @return [Serega::Batch::BatchModel] batch model that encapsulates everything needed to load current batch
+        # Returns BatchModel, an object that encapsulates all batch_loader methods for current point
+        #
+        # @return [BatchModel] batch model that encapsulates everything needed to load current batch
         #
         def batch
           return @batch if instance_variable_defined?(:@batch)
@@ -272,7 +280,7 @@ class Serega
       #
       # Serega additional/patched instance methods
       #
-      # @see Serega
+      # @see Serega::InstanceMethods
       #
       module InstanceMethods
         private

data/lib/serega/validations/attribute/check_opt_delegate.rb

@@ -32,6 +32,7 @@ class Serega
 
             delegate_opts = opts[:delegate]
             check_opt_delegate_to(delegate_opts)
+            check_opt_delegate_key(delegate_opts)
             check_opt_delegate_allow_nil(delegate_opts)
           end
 
@@ -42,13 +43,16 @@ class Serega
             Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :to)
           end
 
-          def check_opt_delegate_allow_nil(delegate_opts)
-            return unless delegate_opts.key?(:allow_nil)
+          def check_opt_delegate_key(delegate_opts)
+            Utils::CheckOptIsStringOrSymbol.call(delegate_opts, :key)
+          end
 
+          def check_opt_delegate_allow_nil(delegate_opts)
             Utils::CheckOptIsBool.call(delegate_opts, :allow_nil)
           end
 
           def check_usage_with_other_params(opts, block)
+            raise SeregaError, "Option :delegate can not be used together with option :key" if opts.key?(:key)
             raise SeregaError, "Option :delegate can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :delegate can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :delegate can not be used together with block" if block

data/lib/serega/validations/check_initiate_params.rb

@@ -39,9 +39,7 @@ class Serega
         end
 
         def check_modifiers
-          Initiate::CheckModifiers.call(serializer_class, opts[:only])
-          Initiate::CheckModifiers.call(serializer_class, opts[:except])
-          Initiate::CheckModifiers.call(serializer_class, opts[:with])
+          Initiate::CheckModifiers.new.call(serializer_class, opts[:only], opts[:with], opts[:except])
         end
 
         def serializer_class

data/lib/serega/validations/initiate/check_modifiers.rb

@@ -10,55 +10,72 @@ class Serega
       # Modifiers validation
       #
       class CheckModifiers
-        class << self
-          # Validates provided fields names are existing attributes
-          #
-          # @param serializer_class [Serega]
-          # @param fields [Hash] validated fields
-          #
-          # @raise [Serega::AttributeNotExist] when modifier not exist as attribute
-          #
-          # @return [void]
-          #
-          def call(serializer_class, fields)
-            return unless fields
+        #
+        # Validates provided fields names are existing attributes
+        #
+        # @param serializer_class [Serega]
+        # @param only [Hash, nil] `only` modifier
+        # @param with [Hash, nil] `with` modifier
+        # @param except [Hash, nil] `except` modifier
+        #
+        # @raise [Serega::AttributeNotExist] when some checked modifier has not existing attribute
+        #
+        # @return [void]
+        #
+        def call(serializer_class, only, with, except)
+          validate(serializer_class, only) if only
+          validate(serializer_class, with) if with
+          validate(serializer_class, except) if except
 
-            validate(serializer_class, fields, [])
-          end
+          raise_errors if any_error?
+        end
 
-          private
+        private
 
-          def validate(serializer_class, fields, prev_names)
-            fields.each do |name, nested_fields|
-              attribute = serializer_class.attributes[name]
+        def validate(serializer_class, fields)
+          fields.each do |name, nested_fields|
+            attribute = serializer_class && serializer_class.attributes[name]
+
+            # Save error when no attribute with checked name exists
+            unless attribute
+              save_error(name)
+              next
+            end
 
-              raise_error(name, prev_names) unless attribute
-              next if nested_fields.empty?
+            # Return when attribute has no nested fields
+            next if nested_fields.empty?
 
-              raise_nested_error(name, prev_names, nested_fields) unless attribute.relation?
-              nested_serializer = attribute.serializer
-              validate(nested_serializer, nested_fields, prev_names + [name])
+            with_parent_name(name) do
+              validate(attribute.serializer, nested_fields)
             end
           end
+        end
 
-          def raise_error(name, prev_names)
-            field_name = field_name(name, prev_names)
+        def parents_names
+          @parents_names ||= []
+        end
 
-            raise Serega::AttributeNotExist, "Attribute #{field_name} not exists"
-          end
+        def with_parent_name(name)
+          parents_names << name
+          yield
+          parents_names.pop
+        end
 
-          def raise_nested_error(name, prev_names, nested_fields)
-            field_name = field_name(name, prev_names)
-            first_nested = nested_fields.keys.first
+        def error_attributes
+          @error_attributes ||= []
+        end
 
-            raise Serega::AttributeNotExist, "Attribute #{field_name} has no :serializer option specified to add nested '#{first_nested}' attribute"
-          end
+        def save_error(name)
+          full_attribute_name = [*parents_names, name].join(".")
+          error_attributes << full_attribute_name
+        end
 
-          def field_name(name, prev_names)
-            res = "'#{name}'"
-            res += " ('#{prev_names.join(".")}.#{name}')" if prev_names.any?
-            res
-          end
+        def raise_errors
+          raise Serega::AttributeNotExist, "Not existing attributes: #{error_attributes.join(", ")}"
+        end
+
+        def any_error?
+          defined?(@error_attributes)
         end
       end
     end

data/lib/serega.rb

@@ -4,9 +4,11 @@ require_relative "serega/version"
 
 # Parent class for your serializers
 class Serega
+  # Frozen hash
   # @return [Hash] frozen hash
   FROZEN_EMPTY_HASH = {}.freeze
 
+  # Frozen array
   # @return [Array] frozen array
   FROZEN_EMPTY_ARRAY = [].freeze
 end
@@ -64,6 +66,7 @@ class Serega
   # Serializers class methods
   #
   module ClassMethods
+    # Returns current config
     # @return [SeregaConfig] current serializer config
     attr_reader :config
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-07 00:00:00.000000000 Z
+date: 2022-12-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -25,6 +25,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - VERSION
 - lib/serega.rb
 - lib/serega/attribute.rb
@@ -92,8 +93,8 @@ homepage: https://github.com/aglushkov/serega
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/aglushkov/serega
   source_code_uri: https://github.com/aglushkov/serega
+  documentation_uri: https://www.rubydoc.info/gems/serega
   changelog_uri: https://github.com/aglushkov/serega/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options: []