surrealist 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '091867794245edb01f2db4525118b6bd26ca2282'
-  data.tar.gz: 00e8caac256b36ecb436c83adec4337381ffafdf
+  metadata.gz: cad5fa813b903c8a83c6618f48a8e5f027244346
+  data.tar.gz: 4c65f03f060c4c93ae2dd036f634bcc84ab77d3e
 SHA512:
-  metadata.gz: 6f58c5d69d760da83b2e87c480d679791d908944abcbc5c027187e473b45bf1124d6a50c416501fb547a38f0e9c1c1585f03ed0157e1b6d2044a455579b4a135
-  data.tar.gz: 6f47c88860840afa21276c62d17bf56dd8845f1867d598fdbbe2594d12dfe39b24ee05d8b9ffe32a3c30c75c2fb4739ae39850867e720f6db6d898ffbfe1b152
+  metadata.gz: 85121fc7dd2a504fe51d03337c52d2ea08784eeca7fbb150f43f047bfe9c915cff1cb813051307cff9a552ad3c564f891eadca1e8dd18e412a850b150f85cd23
+  data.tar.gz: 140e6ced9ee0c3e35b77417e12279699ab0468d7c154e9f8cf5bf89e2a73f7bb065303dc5a39013153acd1c5ca9aeea0b3dd0b477cdcde64cfd5a7f295061bd5

data/.gitignore

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

data/.rspec

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

data/.travis.yml

@@ -4,6 +4,7 @@ cache: bundler
 before_install: gem install bundler
 script: bundle exec rspec
 rvm:
+  - 2.2.0
   - 2.2.5
   - 2.3.1
   - 2.4.0

data/CHANGELOG.md

@@ -1,8 +1,20 @@
+# 0.1.2
+## Added
+* `Any` module for skipping type checks
+* Optional `camelize` argument to convert keys to camelBacks
+
+# 0.1.0
+## Fixed
+* Fix schema mutability issue
+## Changed
+* Change `schema` class method to `json_schema` due to compatibility issues with other gems.
+
 # 0.0.6
-* Add `build_schema` instance method that builds hash from the schema without serializing it to json.
+## Added
+* `build_schema` instance method that builds hash from the schema without serializing it to json.
+## Changed
 * Allow nil values by default.
 * Allow nested objects.
 
-# 0.1.0
-* Change `schema` class method to `json_schema` due to compatibility issues with other gems.
-* Fix schema mutability issue
+
+

data/README.md

@@ -8,16 +8,30 @@ A gem that provides DSL for serialization of plain old Ruby objects to JSON in a
 by defining a `json_schema`. It also provides a trivial type checking in the runtime before serialization.
 [Yard documentation](http://www.rubydoc.info/github/nesaulov/surrealist/master)
 
-## Current status
-In development, not yet ready for real projects.
 
 ## Motivation
 A typical use case for this gem could be, for example, serializing a (decorated) object outside
 of the view context. The schema is described through a hash, so you can build the structure
-of serialized object independently of its methods and attributes.
+of serialized object independently of its methods and attributes, while also having possibility
+to serialize nested objects and structures.
+
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Simple example](#simple-example)
+  * [Nested structures](#nested-structures)
+  * [Nested objects](#nested-objects)
+  * [Usage with Dry::Types](#usage-with-drytypes)
+  * [Build schema](#build-schema)
+  * [Camelization](#camelization)
+  * [Bool and Any](#bool-and-any)
+  * [Type errors](#type-errors)
+  * [Undefined methods in schema](#undefined-methods-in-schema)
+  * [Other notes](#other-notes)
+* [Contributing](#contributing)
+* [License](#license)
 
-## Installation
 
+## Installation
 Add this line to your application's Gemfile:
 
 ``` ruby
@@ -36,7 +50,7 @@ Or install it yourself as:
 ## Usage
 Schema should be defined with a block that contains a hash. Every key of the schema should be
 either a name of a method of the surrealizable object (or it's parents/mixins),
-or - in case value is a hash - a symbol: to build nested JSON structures.
+or - in case you want to build json structure independently from object's structure - a symbol.
 Every value of the hash should be a constant that represents a Ruby class,
 that will be used for type-checks.
 
@@ -69,7 +83,7 @@ end
 
 ``` ruby
 Person.new.surrealize
-# => "{\"foo\":\"This is a string\",\"bar\":42}"
+# => '{ "foo": "This is a string", "bar" :42 }'
 ```
 
 ### Nested structures
@@ -94,12 +108,133 @@ class Person
 end
  
 Person.find_by(email: 'example@email.com').surrealize
-# => "{\"foo\":\"Some string\",\"name\":\"John Doe\",\"nested\":{\"at\":{\"any\":42,\"level\":true}}}"
+# => '{ "foo": "Some string", "name": "John Doe", "nested": { "at": { "any": 42, "level": true } } }'
 ```
 
+### Nested objects
+If you need to serialize nested objects and their attributes, you should
+define a method that calls nested object:
+
+``` ruby
+class User
+  include Surrealist
+  
+  json_schema do
+    {
+      name: String,
+      credit_card: {
+        number: Integer,
+        cvv: Integer,
+      },
+    }
+  end
+ 
+  def name
+    'John Doe'
+  end
+ 
+  def credit_card
+    # Assuming that instance of a CreditCard has methods #number and #cvv defined
+    CreditCard.find_by(holder: name)
+  end
+end
+
+User.new.surrealize
+# => '{ "name": "John Doe", "credit_card": { "number" :1234, "cvv": 322 } }'
+
+```
+
+### 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/)
+by yourself. All built-in features of dry-types work, so if you use, say, `Types::Coercible::String`,
+your data will be coerced if it is able to, otherwise you will get a TypeError.
+Assuming, that you have defined module called `Types`:
+
+``` ruby
+require 'dry-types'
+
+class Car
+  include Surrealist
+ 
+  json_schema do
+    {
+      age:            Types::Coercible::Int,
+      brand:          Types::Coercible::String,
+      doors:          Types::Int.optional,
+      horsepower:     Types::Strict::Int.constrained(gteq: 20),
+      fuel_system:    Types::Any,
+      previous_owner: Types::String,
+    }
+  end
+ 
+  def age;
+    '7';
+  end
+ 
+  def previous_owner;
+    'John Doe';
+  end
+ 
+  def horsepower;
+    140;
+  end
+ 
+  def brand;
+    'Toyota';
+  end
+ 
+  def doors; end
+ 
+  def fuel_system;
+    'Direct injection';
+  end
+end
+
+Car.new.surrealize
+# => '{ "age": 7, "brand": "Toyota", "doors": null, "horsepower": 140, "fuel_system": "Direct injection", "previous_owner": "John Doe" }'
+```
+
+### Build schema
+If you don't need to dump the hash to json, you can use `#build_schema`
+method on the instance. It calculates values and checks types, but returns
+a hash instead of a JSON string. From the previous example:
+
+``` ruby
+Car.new.build_schema
+# => { age: 7, brand: "Toyota", doors: nil, horsepower: 140, fuel_system: "Direct injection", previous_owner: "John Doe" }
+```
+
+### Camelization
+If you need to have keys in camelBack, you can pass optional `camelize` argument
+to `#surrealize`. From the previous example:
+
+``` ruby
+Car.new.surrealize(camelize: true)
+# => '{ "age": 7, "brand": "Toyota", "doors": null, "horsepower": 140, "fuelSystem": "Direct injection", "previousOwner": "John Doe" }'
+```
+
+### Bool and Any
+If you have a parameter that is of boolean type, or if you don't care about the type, you
+can use `Bool` and `Any` respectively.
+
+``` ruby
+class User
+  include Surrealist
+ 
+  json_schema do
+    {
+      age: Any,
+      admin: Bool,
+    }
+  end
+end
+```
+
+
 ### Type Errors
 
-`Surrealist::InvalidTypeError` is thrown if types mismatch.
+`Surrealist::InvalidTypeError` is thrown if types (and dry-types) mismatch.
 
 ``` ruby
 class CreditCard
@@ -109,7 +244,9 @@ class CreditCard
     { number: Integer }
   end
  
-  def number; 'string'; end
+  def number
+    'string'  
+  end
 end
 
 CreditCard.new.surrealize
@@ -134,6 +271,11 @@ Car.new.surrealize
 # => Surrealist::UndefinedMethodError: undefined method `weight' for #<Car:0x007f9bc1dc7fa8>. You have probably defined a key in the schema that doesn't have a corresponding method.
 ```
 
+### 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 ruby of version 2.2 and higher.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nesaulov/surrealist.

data/lib/surrealist/any.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# A module for any type-checks.
+module Any; end

data/lib/surrealist/{boolean.rb → bool.rb}

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
 # A module for boolean type-checks.
-module Boolean; end
+module Bool; end

data/lib/surrealist/builder.rb

@@ -15,13 +15,15 @@ module Surrealist
       #
       # @return [Hash] a hash that will be dumped into JSON.
       def call(schema:, instance:)
-        schema.each do |key, value|
-          if value.is_a?(Hash)
-            parse_hash(hash: value, schema: schema, instance: instance, key: key)
+        schema.each do |schema_key, schema_value|
+          if schema_value.is_a?(Hash)
+            parse_hash(hash: schema_value, schema: schema, instance: instance, key: schema_key)
           else
-            type  = value
-            value = instance.is_a?(Hash) ? instance[key] : instance.send(key)
-            assign_value(method: key, value: value, type: type) { schema[key] = value }
+            type = schema_value
+            schema_value = instance.is_a?(Hash) ? instance[schema_key] : instance.send(schema_key)
+            assign_value(method: schema_key, value: schema_value, type: type) do |coerced_value|
+              schema[schema_key] = coerced_value
+            end
           end
         end
       rescue NoMethodError => e
@@ -85,8 +87,8 @@ module Surrealist
           parse_hash(hash: value, schema: hash, instance: result, key: key)
         else
           type = value
-          assign_value(method: key, value: result, type: type) do
-            schema[method] = schema[method].merge(key => result)
+          assign_value(method: key, value: result, type: type) do |coerced_value|
+            schema[method] = schema[method].merge(key => coerced_value)
           end
         end
       end
@@ -101,28 +103,14 @@ module Surrealist
       #
       # @return [Hash] schema
       def assign_value(method:, value:, type:, &_block)
-        if type_check_passed?(value: value, type: type)
-          yield if block_given?
+        if TypeHelper.valid_type?(value: value, type: type)
+          value = TypeHelper.coerce(type: type, value: value)
+          yield value
         else
           raise Surrealist::InvalidTypeError,
                 "Wrong type for key `#{method}`. Expected #{type}, got #{value.class}."
         end
       end
-
-      # Checks if value returned from a method is an instance of type class specified
-      # in schema or NilClass.
-      #
-      # @param [any] value value returned from a method.
-      # @param [Class] type class representing data type.
-      #
-      # @return [boolean]
-      def type_check_passed?(value:, type:)
-        if type == Boolean
-          [true, false].include?(value)
-        else
-          value.nil? || value.is_a?(type)
-        end
-      end
     end
   end
 end

data/lib/surrealist/instance_methods.rb

@@ -4,13 +4,13 @@ module Surrealist
   # Instance methods that are included to the object's class
   module InstanceMethods
     # Invokes +Surrealist+'s class method +surrealize+
-    def surrealize
-      Surrealist.surrealize(self)
+    def surrealize(camelize: false)
+      Surrealist.surrealize(self, camelize: camelize)
     end
 
     # Invokes +Surrealist+'s class method +build_schema+
-    def build_schema
-      Surrealist.build_schema(self)
+    def build_schema(camelize: false)
+      Surrealist.build_schema(self, camelize: camelize)
     end
   end
 end

data/lib/surrealist/type_helper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # Service class for type checking
+  class TypeHelper
+    DRY_TYPE_CLASS = 'Dry::Types'
+
+    class << self
+      # Checks if value returned from a method is an instance of type class specified
+      # in schema or NilClass.
+      #
+      # @param [any] value value returned from a method.
+      # @param [Class] type class representing data type.
+      #
+      # @return [boolean]
+      def valid_type?(value:, type:)
+        return true if type == Any
+
+        if type == Bool
+          [true, false].include?(value)
+        elsif dry_type?(type)
+          type.try(value).success?
+        else
+          value.nil? || value.is_a?(type)
+        end
+      end
+
+      # Coerces value is it should be coerced
+      #
+      # @param [any] value value that will be coerced
+      # @param [Class] type class representing data type
+      #
+      # @return [any] coerced value
+      def coerce(value:, type:)
+        return value unless dry_type?(type)
+        return value if type.try(value).input == value
+
+        type[value]
+      end
+
+      private
+
+      # Checks if type is an instance of dry-type
+      #
+      # @param [Object] type type to be checked
+      #
+      # @return [Boolean] is type an instance of dry-type
+      def dry_type?(type)
+        if type.respond_to?(:primitive) || type.class.name.nil?
+          true
+        else
+          type.class.name.match(DRY_TYPE_CLASS)
+        end
+      end
+    end
+  end
+end

data/lib/surrealist/utils.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Surrealist
+  # A helper class to camelize hash keys and deep copy objects
+  class Utils
+    class << self
+      # Deep copies the schema hash.
+      #
+      # @param [Object] hash object to be copied
+      #
+      # @return [Object] a copied object
+      def deep_copy(hash)
+        hash.each_with_object({}) do |(key, value), new|
+          new[key] = value.is_a?(Hash) ? deep_copy(value) : value
+        end
+      end
+
+      # Converts hash's keys to camelCase
+      #
+      # @param [Hash] hash a hash to be camelized
+      #
+      # @return [Hash] camelized hash
+      def camelize_hash(hash)
+        if hash.is_a?(Hash)
+          Hash[hash.map { |k, v| [camelize_key(k, false), camelize_hash(v)] }]
+        else
+          hash
+        end
+      end
+
+      private
+
+      # Converts symbol to string and camelizes it
+      #
+      # @param [String | Symbol] key a key to be camelized
+      #
+      # @param [Boolean] first_upper should the first letter be capitalized
+      #
+      # @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
+        elsif key.is_a? String
+          camelize(key, first_upper)
+        else
+          key
+        end
+      end
+
+      # Camelizes a word
+      #
+      # @param [String] snake_word a word to be camelized
+      #
+      # @param [Boolean] first_upper should the first letter be capitalized
+      #
+      # @return [String] camelized string
+      def camelize(snake_word, first_upper = true)
+        if first_upper
+          snake_word.to_s
+                    .gsub(/(?:^|_)([^_\s]+)/) { Regexp.last_match[1].capitalize }
+        else
+          parts = snake_word.split('_', 2)
+          parts[0] << camelize(parts[1]) if parts.size > 1
+          parts[0] || ''
+        end
+      end
+    end
+  end
+end

data/lib/surrealist/version.rb

@@ -2,5 +2,5 @@
 
 module Surrealist
   # Defines the version of Surrealist
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/surrealist.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
-require_relative 'surrealist/class_methods'
-require_relative 'surrealist/instance_methods'
-require_relative 'surrealist/boolean'
+require 'surrealist/class_methods'
+require 'surrealist/instance_methods'
+require 'surrealist/bool'
+require 'surrealist/any'
+require 'surrealist/utils'
+require 'surrealist/type_helper'
 require 'json'
 
 # Main module that provides the +json_schema+ class method and +surrealize+ instance method.
@@ -64,8 +67,8 @@ module Surrealist
   #   User.new.surrealize
   #   # => "{\"name\":\"Nikita\",\"age\":23}"
   #   # For more examples see README
-  def self.surrealize(instance)
-    ::JSON.dump(build_schema(instance))
+  def self.surrealize(instance, camelize:)
+    ::JSON.dump(build_schema(instance, camelize: camelize))
   end
 
   # Builds hash from schema provided in the object's class and type-checks the values.
@@ -106,23 +109,15 @@ module Surrealist
   #   User.new.build_schema
   #   # => { name: 'Nikita', age: 23 }
   #   # For more examples see README
-  def self.build_schema(instance)
+  def self.build_schema(instance, camelize:)
     schema = instance.class.instance_variable_get('@__surrealist_schema')
 
     if schema.nil?
       raise Surrealist::UnknownSchemaError, "Can't serialize #{instance.class} - no schema was provided."
     end
 
+    hash = Builder.call(schema: Surrealist::Utils.deep_copy(schema), instance: instance)
 
-    Builder.call(schema: deep_copy(schema), instance: instance)
-  end
-
-  # Deep copies the schema hash.
-  #
-  # @param [Object] obj object to be coopied
-  #
-  # @return [Object] a copied object
-  def self.deep_copy(obj)
-    Marshal.load(Marshal.dump(obj))
+    camelize ? Surrealist::Utils.camelize_hash(hash) : hash
   end
 end

data/surrealist.gemspec

@@ -22,9 +22,11 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.2.0'
 
   spec.add_development_dependency 'bundler', '~> 1.15'
   spec.add_development_dependency 'rake', '~> 12.0'
   spec.add_development_dependency 'pry', '~> 0.11'
   spec.add_development_dependency 'rspec', '~> 3.6'
+  spec.add_development_dependency 'dry-types', '~> 0.12'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: surrealist
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Nikita Esaulov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-30 00:00:00.000000000 Z
+date: 2017-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
 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.
@@ -84,11 +98,14 @@ files:
 - README.md
 - bin/console
 - lib/surrealist.rb
-- lib/surrealist/boolean.rb
+- lib/surrealist/any.rb
+- lib/surrealist/bool.rb
 - lib/surrealist/builder.rb
 - lib/surrealist/class_methods.rb
 - lib/surrealist/instance_methods.rb
 - lib/surrealist/schema_definer.rb
+- lib/surrealist/type_helper.rb
+- lib/surrealist/utils.rb
 - lib/surrealist/version.rb
 - surrealist.gemspec
 homepage: https://github.com/nesaulov/surrealist
@@ -103,7 +120,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="