surrealist 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 712012011eaaceb220f8811228de4b07c6e08460
-  data.tar.gz: 5ed1ef86483b6dd864a8769359443c7f760e1ae2
+  metadata.gz: c83fe19569dc43edfa87a5a0b8fe4fcbd2f74742
+  data.tar.gz: 8dd0d5fc5e2c1450468bd2d16a026d2a5d6e949e
 SHA512:
-  metadata.gz: b15fda40fbc90382e61703564c4e7a386c521036b60227e902df8e6fd1216c933d1281ac4dc5305f0b641475ebc83187b61354550a603e086026bc0de94d0330
-  data.tar.gz: dc9d2a1a70f6696f5dec95214125b7fe9677ff5c19e6aa9561318127f05b30ea60b0e0dcc694436ac9313879d9fd98e4e23824532ed1f9723534dedc3daa1734
+  metadata.gz: 0a47f6780ffeba32e2b748e588eafb8abf3399d9f464412c0a4e95076809e93b92e346180c2560cb4b1689824accd959d1c2794e8cafa9dad520fe70c6e83243
+  data.tar.gz: afb0df3267229cd475d387449b3246fbe39a5ddb9927de730b229293b82645c946e6f5e3179fe04dcd31533871050453c6dbc1fd33fb86e3b5165626f707f8f7

data/.gitignore

@@ -10,4 +10,3 @@
 .ruby-version
 TODO.md
 *.gem
-.rubocop.yml

data/.rspec

@@ -1,2 +1,3 @@
 --color
+--format doc
 --require spec_helper

data/.rubocop.yml

@@ -0,0 +1,133 @@
+AllCops:
+  TargetRubyVersion: 2.2
+
+# Layout
+
+Layout/AlignParameters:
+  Enabled: true
+
+Layout/EmptyLineBetweenDefs:
+  Exclude:
+    - spec/**/*rb
+
+Layout/IndentArray:
+  EnforcedStyle: consistent
+
+Layout/IndentHash:
+  EnforcedStyle: consistent
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/SpaceInLambdaLiteral:
+  EnforcedStyle: require_space
+
+Layout/SpaceInsideBrackets:
+  Enabled: false
+
+# Lint
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Lint/AmbiguousOperator:
+  Enabled: false
+
+Lint/EmptyWhen:
+  Enabled: false
+
+Lint/NonLocalExitFromIterator:
+  Enabled: false
+
+Lint/RescueType:
+  Enabled: true
+
+# Metrics
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*rb
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/LineLength:
+  Max: 106
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+# Naming
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/PredicateName:
+  NamePrefixBlacklist:
+    - is_
+
+# Performance
+
+Performance/Caller:
+  Enabled: true
+
+Performance/Casecmp:
+  Enabled: true
+
+Performance/UnfreezeString:
+  Enabled: true
+
+# Style
+
+Style/SingleLineMethods:
+  Exclude:
+    - spec/**/*rb
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Dir:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+  ConsistentQuotesInMultiline: true
+
+Style/FormatStringToken:
+  Enabled: true
+
+Style/IfUnlessModifier:
+  Enabled: true
+
+Style/GuardClause:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: true
+
+Style/PerlBackrefs:
+  Enabled: true
+
+Style/RedundantConditional:
+  Enabled: true
+
+Style/RegexpLiteral:
+  EnforcedStyle: mixed
+  Enabled: true
+
+Style/SignalException:
+  EnforcedStyle: only_raise
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: comma

data/.travis.yml

@@ -2,13 +2,12 @@ language: ruby
 sudo: false
 cache: bundler
 before_install: gem install bundler
-script: bundle exec rspec
+script: bundle exec rake
 rvm:
   - 2.2.0
   - 2.2.5
   - 2.3.1
+  - 2.3.5
   - 2.4.0
+  - 2.4.2
   - ruby-head
-matrix:
-  allow_failures:
-    - rvm: ruby-head

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.2.0
+## Added
+* `delegate_surrealization_to` class method
+* `include_namespaces` optional argument
+* `namespaces_nesting_level` optional argument
+* `Surrealist.surrealize_collection` method for collection serialization
+
 # 0.1.4
 ## Added
 * Optional `include_root` argument to wrap schema in a root key. [#15](https://github.com/nesaulov/surrealist/pull/15)

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Issue Guidelines
+
+## Reporting bugs
+If you found a bug, report an issue and describe what's the expected behavior versus what actually happens.
+If the bug causes a crash, attach a full backtrace. If possible, a reproduction script showing the problem
+is highly appreciated.
+
+## Reporting feature requests
+Please provide a concise description of the feature and the reasons behind the request.
+
+# Pull Request Guidelines
+A Pull Request will only be accepted if it addresses a specific issue that was reported previously, or fixes typos, mistakes in documentation etc.
+
+Other requirements:
+
+1) Do not open a pull request if you can't provide tests along with it. If you have problems writing tests, ask for help in the related issue.
+2) Follow the style conventions of the surrounding code. In most cases, this is standard ruby style.
+3) Add API documentation if it's a new feature
+4) Update API documentation if it changes an existing feature
+
+# Asking for help
+If these guidelines aren't helpful, and you're stuck, don't hesitate to open an issue and ask anything.

data/Gemfile

@@ -3,5 +3,15 @@
 source 'https://rubygems.org'
 gemspec
 
-gem 'coveralls', require: false
-gem 'yard', require: false unless ENV['TRAVIS']
+group :development, :test do
+  gem 'activerecord'
+  gem 'coveralls', require: false
+  gem 'data_mapper'
+  gem 'dm-sqlite-adapter'
+  gem 'pry'
+  gem 'rom'
+  gem 'rom-sql'
+  gem 'sequel'
+  gem 'sqlite3'
+  gem 'yard', require: false unless ENV['TRAVIS']
+end

data/README.md

@@ -22,10 +22,13 @@ to serialize nested objects and structures. [Introductory blogpost.](https://med
   * [Simple example](#simple-example)
   * [Nested structures](#nested-structures)
   * [Nested objects](#nested-objects)
+  * [Delegating Surrealization](#delegating-surrealization)
   * [Usage with Dry::Types](#usage-with-drytypes)
   * [Build schema](#build-schema)
   * [Camelization](#camelization)
   * [Include root](#include-root)
+  * [Include namespaces](#include-namespaces)
+  * [Collection Surrealization](#collection-surrealization)
   * [Bool and Any](#bool-and-any)
   * [Type errors](#type-errors)
   * [Undefined methods in schema](#undefined-methods-in-schema)
@@ -146,6 +149,52 @@ User.new.surrealize
 
 ```
 
+### Delegating surrealization
+You can share the `json_schema` between classes:
+``` ruby
+class Host
+  include Surrealist
+ 
+  json_schema do
+    { name: String }
+  end
+ 
+  def name
+    'Host'
+  end
+end
+
+class Guest
+  delegate_surrealization_to Host
+ 
+  def name
+    'Guest'
+  end
+end
+
+Host.new.surrealize
+# => '{ "name": "Host" }'
+Guest.new.surrealize
+# => '{ "name": "Guest" }'
+```
+Schema delegation works without inheritance as well, so if you wish you can
+delegate surrealization not only to parent classes, but to any class. Please note that
+in this case you have to `include Surrealist` in class that delegates schema as well.
+``` ruby
+class Potato
+  include Surrealist
+  delegate_surrealization_to Host
+ 
+  def name
+    'Potato'
+  end
+end
+
+Potato.new.surrealize
+# => '{ "name": "Potato" }'
+```
+
+
 ### Usage with Dry::Types
 You can use `Dry::Types` for type checking. Note that Surrealist does not ship
 with dry-types by default, so you should do the [installation and configuration](http://dry-rb.org/gems/dry-types/)
@@ -255,7 +304,55 @@ end
 Animal::Dog.new.surrealize(include_root: true)
 # => '{ "dog": { "breed": "Collie" } }'
 ```
-Nesting namespaces are [yet to be implemented.](https://github.com/nesaulov/surrealist/issues/14)
+
+### Include namespaces
+You can build wrap schema into a nested hash from namespaces of the object's class.
+``` ruby
+class BusinessSystem::Cashout::ReportSystem::Withdraws
+  include Surrealist
+ 
+  json_schema do
+    { withdraws_amount: Integer }
+  end
+ 
+  def withdraws_amount
+    34
+  end
+end
+ 
+withdraws = BusinessSystem::Cashout::ReportSystem::Withdraws.new
+ 
+withdraws.surrealize(include_namespaces: true)
+# => '{ "business_system": { "cashout": { "report_system": { "withdraws": { "withdraws_amount": 34 } } } } }' 
+```
+By default all namespaces will be taken. If you want you can explicitly specify the level of nesting:
+``` ruby
+withdraws.surrealize(include_namespaces: true, namespaces_nesting_level: 2)
+# => '{ "report_system": { "withdraws": { "withdraws_amount": 34 } } }'
+```
+
+### Collection Surrealization
+Since 0.2.0 Surrealist has API for collection serialization. Example for ActiveRecord:
+``` ruby
+class User < ActiveRecord::Base
+  include Surrealist
+ 
+  json_schema do
+    { name: String, age: Integer }
+  end
+end
+ 
+users = User.all
+# => [#<User:0x007fa1485de878 id: 1, name: "Nikita", age: 23>, #<User:0x007fa1485de5f8 id: 2, name: "Alessandro", age: 24>]
+ 
+Surrealist.surrealize_collection(users)
+# => '[{ "name": "Nikita", "age": 23 }, { "name": "Alessandro", "age": 24 }]'
+```
+You can find motivation behind introducing new API versus monkey-patching [here](https://alessandrominali.github.io/monkey_patching_real_example).  
+`#surrealize_collection` works for all data structures that respond to `#each`. All ActiveRecord
+features (like associations, inheritance etc) are supported and covered. Other ORMs should work without
+issues as well, tests are in progress. All optional arguments (`camelize`, `include_root` etc) are also supported.
+Guides on where to use `#surrealize_collection` vs `#surrealize` for all ORMs are coming.
 
 ### Bool and Any
 If you have a parameter that is of boolean type, or if you don't care about the type, you
@@ -274,9 +371,7 @@ class User
 end
 ```
 
-
 ### Type Errors
-
 `Surrealist::InvalidTypeError` is thrown if types (and dry-types) mismatch.
 
 ``` ruby
@@ -297,7 +392,6 @@ CreditCard.new.surrealize
 ```
 
 ### Undefined methods in schema
-
 `Surrealist::UndefinedMethodError` is thrown if a key defined in the schema does not have
 a corresponding method defined in the object.
 
@@ -317,14 +411,11 @@ Car.new.surrealize
 ### Other notes
 * nil values are allowed by default, so if you have, say, `age: String`, but the actual value is nil,
 type check will be passed. If you want to be strict about `nil`s consider using `Dry::Types`.
-* Surrealist requires MRI ruby of version 2.2 and higher.
+* Surrealist [officially supports](https://travis-ci.org/nesaulov/surrealist) MRI Ruby 2.2+ but should be working on other platforms as well.
 
 ## Roadmap
 Here is a list of features that are not implemented yet (contributions are welcome):
-* [ActiveRecord_Relation serialization](https://github.com/nesaulov/surrealist/issues/13)
 * [Collection serialization](https://github.com/nesaulov/surrealist/issues/12)
-* [Delegating serialization to parent class](https://github.com/nesaulov/surrealist/issues/11)
-* [Having nested namespaces being surrealized](https://github.com/nesaulov/surrealist/issues/14)
 
 ## Contributing
 Bug reports and pull requests are welcome on GitHub at https://github.com/nesaulov/surrealist.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[rubocop spec]

data/lib/surrealist/carrier.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # A data structure to carry arguments across methods.
+  class Carrier
+    # Public wrapper for Carrier.
+    #
+    # @param [Boolean] camelize optional argument for converting hash to camelBack.
+    # @param [Boolean] include_root optional argument for having the root key of the resulting hash
+    #   as instance's class name.
+    # @param [Boolean] include_namespaces optional argument for having root key as a nested hash of
+    #   instance's namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: '3 kilos' } })
+    # @param [Integer] namespaces_nesting_level level of namespaces nesting.
+    #
+    # @raise ArgumentError if types of arguments are wrong.
+    #
+    # @return [Carrier] self if type checks were passed.
+    def self.call(camelize:, include_root:, include_namespaces:, namespaces_nesting_level:)
+      new(camelize, include_root, include_namespaces, namespaces_nesting_level).sanitize!
+    end
+
+    attr_reader :camelize, :include_root, :include_namespaces, :namespaces_nesting_level
+
+    def initialize(camelize, include_root, include_namespaces, namespaces_nesting_level)
+      @camelize                 = camelize
+      @include_root             = include_root
+      @include_namespaces       = include_namespaces
+      @namespaces_nesting_level = namespaces_nesting_level
+    end
+
+    # Performs type checks
+    #
+    # @return [Carrier] self if check were passed
+    def sanitize!
+      check_booleans!
+      check_namespaces_nesting!
+      self
+    end
+
+    private
+
+    # Checks all boolean arguments
+    # @raise ArgumentError
+    def check_booleans!
+      booleans_hash.each do |key, value|
+        unless [true, false].include?(value)
+          raise ArgumentError, "Expected `#{key}` to be either true or false, got #{value}"
+        end
+      end
+    end
+
+    # Helper hash for all boolean arguments
+    def booleans_hash
+      { camelize: camelize, include_root: include_root, include_namespaces: include_namespaces }
+    end
+
+    # Checks if +namespaces_nesting_level+ is a positive integer
+    # @raise ArgumentError
+    def check_namespaces_nesting!
+      unless namespaces_nesting_level.is_a?(Integer)
+        Surrealist::ExceptionRaiser.raise_invalid_nesting!(namespaces_nesting_level)
+      end
+
+      if namespaces_nesting_level <= 0
+        Surrealist::ExceptionRaiser.raise_invalid_nesting!(namespaces_nesting_level)
+      end
+    end
+  end
+end

data/lib/surrealist/class_methods.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'builder'
-require_relative 'schema_definer'
-
 module Surrealist
   # Class methods that are extended by the object.
   module ClassMethods
@@ -57,5 +54,44 @@ module Surrealist
     def json_schema(&_block)
       SchemaDefiner.call(self, yield)
     end
+
+    # A DSL method to delegate schema in a declarative style. Must reference a valid
+    # class that includes Surrealist
+    #
+    # @param [Class] klass
+    #
+    # @example DSL usage example
+    #   class Host
+    #     include Surrealist
+    #
+    #     json_schema do
+    #       { name: String }
+    #     end
+    #
+    #     def name
+    #       'Parent'
+    #     end
+    #   end
+    #
+    #   class Guest < Host
+    #     delegate_surrealization_to Host
+    #
+    #     def name
+    #       'Child'
+    #     end
+    #   end
+    #
+    #   Guest.new.surrealize
+    #   # => "{\"name\":\"Child\"}"
+    #   # For more examples see README
+    def delegate_surrealization_to(klass)
+      raise TypeError, "Expected type of Class got #{klass.class} instead" unless klass.is_a?(Class)
+
+      unless klass.included_modules.include?(Surrealist)
+        Surrealist::ExceptionRaiser.raise_invalid_schema_delegation!
+      end
+
+      instance_variable_set('@__surrealist_schema_parent', klass)
+    end
   end
 end

data/lib/surrealist/copier.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # A helper class for deep copying and wrapping hashes.
+  class Copier
+    class << self
+      # Deeply copies the schema hash and wraps it if there is a need to.
+      #
+      # @param [Object] hash object to be copied.
+      # @param [String] klass instance's class name.
+      # @param [Object] carrier instance of Carrier class that carries arguments passed to +surrealize+
+      #
+      # @return [Hash] a copied hash.
+      def deep_copy(hash:, klass: false, carrier:)
+        namespaces_condition = carrier.include_namespaces || carrier.namespaces_nesting_level != DEFAULT_NESTING_LEVEL # rubocop:disable Metrics/LineLength
+
+        return copy_hash(hash) unless carrier.include_root || namespaces_condition
+
+        Surrealist::ExceptionRaiser.raise_unknown_root! unless klass
+
+        if namespaces_condition
+          wrap_schema_into_namespace(schema: hash, klass: klass, carrier: carrier)
+        elsif carrier.include_root
+          wrap_schema_into_root(schema: hash, klass: klass, carrier: carrier)
+        end
+      end
+
+      private
+
+      # Goes through the hash recursively and deeply copies it.
+      #
+      # @param [Hash] hash the hash to be copied.
+      # @param [Hash] wrapper the wrapper of the resulting hash.
+      #
+      # @return [Hash] deeply copied hash.
+      def copy_hash(hash, wrapper: {})
+        hash.each_with_object(wrapper) do |(key, value), new|
+          new[key] = value.is_a?(Hash) ? copy_hash(value) : value
+        end
+      end
+
+      # Wraps schema into a root key if `include_root` is passed to Surrealist.
+      #
+      # @param [Hash] schema schema hash.
+      # @param [String] klass name of the class where schema is defined.
+      # @param [Object] carrier instance of Carrier class that carries arguments passed to +surrealize+
+      #
+      # @return [Hash] a hash with schema wrapped inside a root key.
+      def wrap_schema_into_root(schema:, klass:, carrier:)
+        actual_class = Surrealist::StringUtils.extract_class(klass)
+        root_key = if carrier.camelize
+                     Surrealist::StringUtils.camelize(actual_class, false).to_sym
+                   else
+                     Surrealist::StringUtils.underscore(actual_class).to_sym
+                   end
+        result = Hash[root_key => {}]
+        copy_hash(schema, wrapper: result[root_key])
+
+        result
+      end
+
+      # Wraps schema into a nested hash of namespaces.
+      #
+      # @param [Hash] schema main schema.
+      # @param [String] klass name of the class where schema is defined.
+      # @param [Object] carrier instance of Carrier class that carries arguments passed to +surrealize+
+      #
+      # @return [Hash] nested hash (see +inject_schema+)
+      def wrap_schema_into_namespace(schema:, klass:, carrier:)
+        nested_hash = Surrealist::StringUtils.break_namespaces(
+          klass,
+          camelize: carrier.camelize,
+          nesting_level: carrier.namespaces_nesting_level,
+        )
+
+        inject_schema(nested_hash, copy_hash(schema))
+      end
+
+      # Injects one hash into another nested hash.
+      #
+      # @param [Hash] hash wrapper-hash.
+      # @param [Hash] sub_hash hash to be injected.
+      #
+      # @example wrapping hash
+      #  hash = { one: { two: { three: {} } } }
+      #  sub_hash = { four: '4' }
+      #
+      #  inject_schema(hash, sub_hash)
+      #  # => { one: { two: { three: { four: '4' } } } }
+      #
+      # @return [Hash] resulting hash.
+      def inject_schema(hash, sub_hash)
+        hash.each do |k, v|
+          v == {} ? hash[k] = sub_hash : inject_schema(v, sub_hash)
+        end
+      end
+    end
+  end
+end

data/lib/surrealist/exception_raiser.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # Error class for classes without defined +schema+.
+  class UnknownSchemaError < RuntimeError; end
+
+  # Error class for classes with +json_schema+ defined not as a hash.
+  class InvalidSchemaError < RuntimeError; end
+
+  # Error class for +NoMethodError+.
+  class UndefinedMethodError < RuntimeError; end
+
+  # Error class for failed type-checks.
+  class InvalidTypeError < TypeError; end
+
+  # Error class for undefined root keys for schema wrapping.
+  class UnknownRootError < RuntimeError; end
+
+  # Error class for undefined class to delegate schema.
+  class InvalidSchemaDelegation < RuntimeError; end
+
+  # Error class for invalid object given to iteratively apply surrealize.
+  class InvalidCollectionError < ArgumentError; end
+
+  # Error class for cases where +namespaces_nesting_level+ is set to 0.
+  class InvalidNestingLevel < RuntimeError; end
+
+  # A class that raises all Surrealist exceptions
+  class ExceptionRaiser
+    class << self
+      # Raises Surrealist::InvalidSchemaDelegation if destination of delegation does not
+      # include Surrealist.
+      #
+      # @raise Surrealist::InvalidSchemaDelegation
+      def raise_invalid_schema_delegation!
+        raise Surrealist::InvalidSchemaDelegation, 'Class does not include Surrealist'
+      end
+
+      # Raises Surrealist::UnknownSchemaError
+      #
+      # @param [Object] instance instance of the class without schema defined.
+      #
+      # @raise Surrealist::UnknownSchemaError
+      def raise_unknown_schema!(instance)
+        raise Surrealist::UnknownSchemaError,
+              "Can't serialize #{instance.class} - no schema was provided."
+      end
+
+      # Raises Surrealist::UnknownRootError if class's name is unknown.
+      #
+      # @raise Surrealist::UnknownRootError
+      def raise_unknown_root!
+        raise Surrealist::UnknownRootError, "Can't wrap schema in root key - class name was not passed"
+      end
+
+      # Raises Surrealist::InvalidCollectionError
+      #
+      # @raise Surrealist::InvalidCollectionError
+      def raise_invalid_collection!
+        raise Surrealist::InvalidCollectionError, "Can't serialize collection - must respond to :each"
+      end
+
+      # Raises ArgumentError if namespaces_nesting_level is not an integer.
+      #
+      # @raise ArgumentError
+      def raise_invalid_nesting!(value)
+        raise ArgumentError,
+              "Expected `namespaces_nesting_level` to be a positive integer, got: #{value}"
+      end
+    end
+  end
+end

data/lib/surrealist/hash_utils.rb

@@ -1,29 +1,9 @@
 # frozen_string_literal: true
 
 module Surrealist
-  # A helper class to camelize, wrap and deeply copy hashes.
+  # A helper class for hashes transformations.
   class HashUtils
     class << self
-      # Deeply copies the schema hash and wraps it if there is a need to.
-      #
-      # @param [Object] hash object to be copied.
-      # @param [Boolean] include_root optional argument for including root in the hash.
-      # @param [Boolean] camelize optional argument for camelizing the root key of the hash.
-      # @param [String] klass instance's class name.
-      #
-      # @return [Object] a copied object
-      def deep_copy(hash:, include_root: false, camelize: false, klass: false)
-        return copy_hash(hash) unless include_root
-        raise_unknown_root! if include_root && !klass
-
-        actual_class = extract_class(klass)
-        root_key = camelize ? camelize(actual_class, false).to_sym : underscore(actual_class).to_sym
-        object = Hash[root_key => {}]
-        copy_hash(hash, wrapper: object[root_key])
-
-        object
-      end
-
       # Converts hash's keys to camelBack keys.
       #
       # @param [Hash] hash a hash to be camelized.
@@ -39,18 +19,6 @@ module Surrealist
 
       private
 
-      # Goes through the hash recursively and deeply copies it.
-      #
-      # @param [Hash] hash the hash to be copied.
-      # @param [Hash] wrapper the wrapper of the resulting hash.
-      #
-      # @return [Hash] deeply copied hash.
-      def copy_hash(hash, wrapper: {})
-        hash.each_with_object(wrapper) do |(key, value), new|
-          new[key] = value.is_a?(Hash) ? copy_hash(value) : value
-        end
-      end
-
       # Converts symbol to string and camelizes it.
       #
       # @param [String | Symbol] key a key to be camelized.
@@ -59,73 +27,13 @@ module Surrealist
       # @return [String | Symbol] camelized key of a hash.
       def camelize_key(key, first_upper = true)
         if key.is_a? Symbol
-          camelize(key.to_s, first_upper).to_sym
+          Surrealist::StringUtils.camelize(key.to_s, first_upper).to_sym
         elsif key.is_a? String
-          camelize(key, first_upper)
+          Surrealist::StringUtils.camelize(key, first_upper)
         else
           key
         end
       end
-
-      # Camelizes a string.
-      #
-      # @param [String] snake_string a string to be camelized.
-      # @param [Boolean] first_upper should the first letter be capitalized.
-      #
-      # @return [String] camelized string.
-      def camelize(snake_string, first_upper = true)
-        if first_upper
-          snake_string.to_s
-                    .gsub(/(?:^|_)([^_\s]+)/) { Regexp.last_match[1].capitalize }
-        else
-          parts = snake_string.split('_', 2)
-          parts[0] << camelize(parts[1]) if parts.size > 1
-          parts[0] || ''
-        end
-      end
-
-      # Clones a string and converts first character to lower case.
-      #
-      # @param [String] string a string to be cloned.
-      #
-      # @return [String] new string with lower cased first character.
-      def uncapitalize(string)
-        str = string.dup
-        str[0] = str[0].downcase
-        str
-      end
-
-      # Converts a string to snake_case.
-      #
-      # @param [String] string a string to be underscored.
-      #
-      # @return [String] underscored string.
-      def underscore(string)
-        string.gsub('::', '_')
-          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-          .tr('-', '_')
-          .downcase
-      end
-
-      # Extract last class from a namespace.
-      #
-      # @param [String] string full namespace
-      #
-      # @example Extract class
-      #   extract_class('Animal::Dog::Collie') # => 'Collie'
-      #
-      # @return [String] extracted class
-      def extract_class(string)
-        uncapitalize(string.split('::').last)
-      end
-
-      # Raises Surrealist::UnknownRootError if class's name is unknown.
-      #
-      # @raise Surrealist::UnknownRootError
-      def raise_unknown_root!
-        raise Surrealist::UnknownRootError, "Can't wrap schema in root key - class name was not passed"
-      end
     end
   end
 end

data/lib/surrealist/instance_methods.rb

@@ -3,14 +3,71 @@
 module Surrealist
   # Instance methods that are included to the object's class
   module InstanceMethods
-    # Invokes +Surrealist+'s class method +surrealize+
-    def surrealize(camelize: false, include_root: false)
-      Surrealist.surrealize(instance: self, camelize: camelize, include_root: include_root)
+    # Dumps the object's methods corresponding to the schema
+    # provided in the object's class and type-checks the values.
+    #
+    # @param [Boolean] camelize optional argument for converting hash to camelBack.
+    # @param [Boolean] include_root optional argument for having the root key of the resulting hash
+    #   as instance's class name.
+    # @param [Boolean] include_namespaces optional argument for having root key as a nested hash of
+    #   instance's namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: '3 kilos' } })
+    # @param [Integer] namespaces_nesting_level level of namespaces nesting.
+    #
+    # @return [String] a json-formatted string corresponding to the schema
+    #   provided in the object's class. Values will be taken from the return values
+    #   of appropriate methods from the object.
+    #
+    # @raise +Surrealist::UnknownSchemaError+ if no schema was provided in the object's class.
+    #
+    # @raise +Surrealist::InvalidTypeError+ if type-check failed at some point.
+    #
+    # @raise +Surrealist::UndefinedMethodError+ if a key defined in the schema
+    #   does not have a corresponding method on the object.
+    #
+    # @example Define a schema and surrealize the object
+    #   class User
+    #     include Surrealist
+    #
+    #     json_schema do
+    #       {
+    #         name: String,
+    #         age: Integer,
+    #       }
+    #     end
+    #
+    #     def name
+    #       'Nikita'
+    #     end
+    #
+    #     def age
+    #       23
+    #     end
+    #   end
+    #
+    #   User.new.surrealize
+    #   # => "{\"name\":\"Nikita\",\"age\":23}"
+    #   # For more examples see README
+    def surrealize(camelize: false, include_root: false, include_namespaces: false, namespaces_nesting_level: DEFAULT_NESTING_LEVEL) # rubocop:disable Metrics/LineLength
+      JSON.dump(
+        build_schema(
+          camelize: camelize,
+          include_root: include_root,
+          include_namespaces: include_namespaces,
+          namespaces_nesting_level: namespaces_nesting_level,
+        ),
+      )
     end
 
     # Invokes +Surrealist+'s class method +build_schema+
-    def build_schema(camelize: false, include_root: false)
-      Surrealist.build_schema(instance: self, camelize: camelize, include_root: include_root)
+    def build_schema(camelize: false, include_root: false, include_namespaces: false, namespaces_nesting_level: DEFAULT_NESTING_LEVEL) # rubocop:disable Metrics/LineLength
+      carrier = Surrealist::Carrier.call(
+        camelize: camelize,
+        include_namespaces: include_namespaces,
+        include_root: include_root,
+        namespaces_nesting_level: namespaces_nesting_level,
+      )
+
+      Surrealist.build_schema(instance: self, carrier: carrier)
     end
   end
 end

data/lib/surrealist/string_utils.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # A helper class for strings transformations.
+  class StringUtils
+    class << self
+      # Converts a string to snake_case.
+      #
+      # @param [String] string a string to be underscored.
+      #
+      # @return [String] underscored string.
+      def underscore(string)
+        string.gsub('::', '_')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-', '_')
+          .downcase
+      end
+
+      # Camelizes a string.
+      #
+      # @param [String] snake_string a string to be camelized.
+      # @param [Boolean] first_upper should the first letter be capitalized.
+      #
+      # @return [String] camelized string.
+      def camelize(snake_string, first_upper = true)
+        if first_upper
+          snake_string.to_s
+            .gsub(/(?:^|_)([^_\s]+)/) { Regexp.last_match[1].capitalize }
+        else
+          parts = snake_string.split('_', 2)
+          parts[0] << camelize(parts[1]) if parts.size > 1
+          parts[0] || ''
+        end
+      end
+
+      # Extracts bottom-level class from a namespace.
+      #
+      # @param [String] string full namespace
+      #
+      # @example Extract class
+      #   extract_class('Animal::Dog::Collie') # => 'Collie'
+      #
+      # @return [String] extracted class
+      def extract_class(string)
+        uncapitalize(string.split('::').last)
+      end
+
+      # Extracts n amount of classes from a namespaces and returns a nested hash.
+      #
+      # @param [String] klass full namespace as a string.
+      # @param [Boolean] camelize optional camelize argument.
+      # @param [Integer] nesting_level level of required nesting.
+      #
+      # @example 3 levels
+      #   klass = 'Business::System::Cashier::Reports::Withdraws'
+      #   break_namespaces(klass, camelize: false, nesting_level: 3)
+      #   # => { cashier: { reports: { withdraws: {} } } }
+      #
+      # @raise Surrealist::InvalidNestingLevel if nesting level is specified as 0.
+      #
+      # @return [Hash] a nested hash.
+      def break_namespaces(klass, camelize:, nesting_level:)
+        Surrealist::ExceptionRaiser.raise_invalid_nesting!(nesting_level) unless nesting_level > 0
+        arr = klass.split('::')
+        arr.last(nesting_level).reverse.inject({}) do |a, n|
+          camelize ? Hash[camelize(uncapitalize(n), false).to_sym => a] : Hash[underscore(n).to_sym => a]
+        end
+      end
+
+      private
+
+      # Clones a string and converts first character to lower case.
+      #
+      # @param [String] string a string to be cloned.
+      #
+      # @return [String] new string with lower cased first character.
+      def uncapitalize(string)
+        str = string.dup
+        str[0] = str[0].downcase
+        str
+      end
+    end
+  end
+end

data/lib/surrealist/type_helper.rb

@@ -4,7 +4,7 @@ module Surrealist
   # Service class for type checking
   class TypeHelper
     # Dry-types class matcher
-    DRY_TYPE_CLASS = 'Dry::Types'
+    DRY_TYPE_CLASS = 'Dry::Types'.freeze
 
     class << self
       # Checks if value returned from a method is an instance of type class specified

data/lib/surrealist/version.rb

@@ -2,5 +2,5 @@
 
 module Surrealist
   # Defines the version of Surrealist
-  VERSION = '0.1.4'
+  VERSION = '0.2.0'.freeze
 end

data/lib/surrealist.rb

@@ -1,29 +1,23 @@
 # frozen_string_literal: true
 
-require 'surrealist/class_methods'
-require 'surrealist/instance_methods'
-require 'surrealist/bool'
 require 'surrealist/any'
+require 'surrealist/bool'
+require 'surrealist/builder'
+require 'surrealist/carrier'
+require 'surrealist/class_methods'
+require 'surrealist/copier'
+require 'surrealist/exception_raiser'
 require 'surrealist/hash_utils'
+require 'surrealist/instance_methods'
+require 'surrealist/schema_definer'
+require 'surrealist/string_utils'
 require 'surrealist/type_helper'
 require 'json'
 
 # Main module that provides the +json_schema+ class method and +surrealize+ instance method.
 module Surrealist
-  # Error class for classes without defined +schema+.
-  class UnknownSchemaError < RuntimeError; end
-
-  # Error class for classes with +json_schema+ defined not as a hash.
-  class InvalidSchemaError < RuntimeError; end
-
-  # Error class for +NoMethodError+.
-  class UndefinedMethodError < RuntimeError; end
-
-  # Error class for failed type-checks.
-  class InvalidTypeError < TypeError; end
-
-  # Error class for undefined root keys for schema wrapping.
-  class UnknownRootError < RuntimeError; end
+  # Default namespaces nesting level
+  DEFAULT_NESTING_LEVEL = 666
 
   class << self
     # @param [Class] base class to include/extend +Surrealist+.
@@ -32,58 +26,43 @@ module Surrealist
       base.include(Surrealist::InstanceMethods)
     end
 
-    # Dumps the object's methods corresponding to the schema
-    # provided in the object's class and type-checks the values.
+    # Iterates over a collection of Surrealist Objects and
+    # maps surrealize to each record.
     #
-    # @param [Object] instance of a class that has +Surrealist+ included.
+    # @param [Object] Collection of instances of a class that has +Surrealist+ included.
     # @param [Boolean] camelize optional argument for converting hash to camelBack.
     # @param [Boolean] include_root optional argument for having the root key of the resulting hash
     #   as instance's class name.
     #
-    # @return [String] a json-formatted string corresponding to the schema
-    #   provided in the object's class. Values will be taken from the return values
+    # @return [Object] the Collection#map with elements being json-formatted string corresponding
+    #   to the schema provided in the object's class. Values will be taken from the return values
     #   of appropriate methods from the object.
     #
-    # @raise +Surrealist::UnknownSchemaError+ if no schema was provided in the object's class.
-    #
-    # @raise +Surrealist::InvalidTypeError+ if type-check failed at some point.
-    #
-    # @raise +Surrealist::UndefinedMethodError+ if a key defined in the schema
-    #   does not have a corresponding method on the object.
-    #
-    # @example Define a schema and surrealize the object
-    #   class User
-    #     include Surrealist
-    #
-    #     json_schema do
-    #       {
-    #         name: String,
-    #         age: Integer,
-    #       }
-    #     end
+    # @raise +Surrealist::InvalidCollectionError+ if invalid collection passed.
     #
-    #     def name
-    #       'Nikita'
-    #     end
-    #
-    #     def age
-    #       23
-    #     end
-    #   end
-    #
-    #   User.new.surrealize
-    #   # => "{\"name\":\"Nikita\",\"age\":23}"
+    # @example surrealize a given collection of Surrealist objects
+    #   Surrealist.surrealize_collection(User.all)
+    #   # => "[{\"name\":\"Nikita\",\"age\":23}, {\"name\":\"Alessandro\",\"age\":24}]"
     #   # For more examples see README
-    def surrealize(instance:, camelize:, include_root:)
-      ::JSON.dump(build_schema(instance: instance, camelize: camelize, include_root: include_root))
+    def surrealize_collection(collection, camelize: false, include_root: false, include_namespaces: false, namespaces_nesting_level: DEFAULT_NESTING_LEVEL) # rubocop:disable Metrics/LineLength
+      unless collection.respond_to?(:each)
+        raise Surrealist::ExceptionRaiser.raise_invalid_collection!
+      end
+
+      JSON.dump(collection.map do |record|
+        record.build_schema(
+          camelize: camelize,
+          include_root: include_root,
+          include_namespaces: include_namespaces,
+          namespaces_nesting_level: namespaces_nesting_level,
+        )
+      end)
     end
 
     # Builds hash from schema provided in the object's class and type-checks the values.
     #
     # @param [Object] instance of a class that has +Surrealist+ included.
-    # @param [Boolean] camelize optional argument for converting hash to camelBack.
-    # @param [Boolean] include_root optional argument for having the root key of the resulting hash
-    #   as instance's class name.
+    # @param [Object] carrier instance of Carrier class that carries arguments passed to +surrealize+
     #
     # @return [Hash] a hash corresponding to the schema
     #   provided in the object's class. Values will be taken from the return values
@@ -119,29 +98,20 @@ module Surrealist
     #   User.new.build_schema
     #   # => { name: 'Nikita', age: 23 }
     #   # For more examples see README
-    def build_schema(instance:, camelize:, include_root:)
-      schema = instance.class.instance_variable_get('@__surrealist_schema')
+    def build_schema(instance:, carrier:)
+      delegatee = instance.class.instance_variable_get('@__surrealist_schema_parent')
+      schema = (delegatee || instance.class).instance_variable_get('@__surrealist_schema')
 
-      raise_unknown_schema!(instance) if schema.nil?
+      Surrealist::ExceptionRaiser.raise_unknown_schema!(instance) if schema.nil?
 
-      normalized_schema = Surrealist::HashUtils.deep_copy(
-        hash:         schema,
-        klass:        instance.class.name,
-        camelize:     camelize,
-        include_root: include_root,
+      normalized_schema = Surrealist::Copier.deep_copy(
+        hash:    schema,
+        klass:   instance.class.name,
+        carrier: carrier,
       )
 
       hash = Builder.call(schema: normalized_schema, instance: instance)
-      camelize ? Surrealist::HashUtils.camelize_hash(hash) : hash
-    end
-
-    # Raises Surrealist::UnknownSchemaError
-    #
-    # @param [Object] instance instance of the class without schema defined.
-    #
-    # @raise Surrealist::UnknownSchemaError
-    def raise_unknown_schema!(instance)
-      raise Surrealist::UnknownSchemaError, "Can't serialize #{instance.class} - no schema was provided."
+      carrier.camelize ? Surrealist::HashUtils.camelize_hash(hash) : hash
     end
   end
 end

data/surrealist.gemspec

@@ -29,4 +29,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry', '~> 0.11'
   spec.add_development_dependency 'rspec', '~> 3.6'
   spec.add_development_dependency 'dry-types', '~> 0.12'
+  spec.add_development_dependency 'rubocop', '~> 0.50.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: surrealist
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Nikita Esaulov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-06 00:00:00.000000000 Z
+date: 2017-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.50.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.50.0
 description: A gem that provides DSL for serialization of plain old Ruby objects to
   JSON in a declarative style by defining a `schema`. It also provides a trivial type
   checking in the runtime before serialization.
@@ -91,20 +105,27 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
+- Rakefile
 - bin/console
 - lib/surrealist.rb
 - lib/surrealist/any.rb
 - lib/surrealist/bool.rb
 - lib/surrealist/builder.rb
+- lib/surrealist/carrier.rb
 - lib/surrealist/class_methods.rb
+- lib/surrealist/copier.rb
+- lib/surrealist/exception_raiser.rb
 - lib/surrealist/hash_utils.rb
 - lib/surrealist/instance_methods.rb
 - lib/surrealist/schema_definer.rb
+- lib/surrealist/string_utils.rb
 - lib/surrealist/type_helper.rb
 - lib/surrealist/version.rb
 - surrealist-icon.png
@@ -129,7 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: A gem that provides DSL for serialization of plain old Ruby objects to JSON