deserializer 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d2d925b16aaf70730f68ed799b22236a2b4a9c1b
-  data.tar.gz: 291d5ba90c44ddd31eeab94c314f16f414ecf7df
+  metadata.gz: 3e444e500d391065ce2aed5b2b41cb605fa443df
+  data.tar.gz: ba9db864ddb2d65dce89ddcb494939eda0d05428
 SHA512:
-  metadata.gz: df1caed559319d4c42f6770408172d600c8511260126a8eec742d645586d14861e8468999f094d195f0a9462c0bf09efe2afc3f289166f3c42f330e750e96e1d
-  data.tar.gz: 2a87db6f696784599033d89f4b41abad6bb2094890f7a403c83182afab53094c0714a7ff8d276a0a113c00a9e9b9990498f5b723721c5b23dc317dee305e36c5
+  metadata.gz: c84a34731a8b4e26b93b8ac96116bf39116a9617676330b32465e1ff8ab743491a33c54d8eb321cad436d5ab8a1fc6954be981405066e9b48d62459cb6d47911
+  data.tar.gz: 302c940e2185dfc3eaf5471cf9ea34ca276a5b8a5327f7d94a216d55dc27e4a527ec39a2b35a832885ea6c7d826d286d7725d4e06f0957ebe1bae08e20c5932c

data/Gemfile.lock

@@ -1,12 +1,21 @@
 PATH
   remote: .
   specs:
-    deserializer (0.2.0)
+    deserializer (0.3.0)
+      activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (4.2.5)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
     docile (1.1.5)
+    i18n (0.7.0)
+    json (1.8.3)
     minitest (5.7.0)
     multi_json (1.11.1)
     rake (10.4.2)
@@ -15,6 +24,9 @@ GEM
       multi_json (~> 1.0)
       simplecov-html (~> 0.9.0)
     simplecov-html (0.9.0)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -1,12 +1,13 @@
 # Deserializer
-
-Hash transformation and sanitization. Deserialization of complex parameters into a hash that an AR model can take. 
-
-Lets you have a reverse ActiveModel::Sereializer-like interface that allows for easy create and update without having to write heavy controllers.
+## Features
+- Hash transformation and sanitization
+- Deserialization of complex parameters into a hash that an AR model can take
+- Avoid having multiple definitions in fragile arrays when using strong params
+- Easy create and update from JSON without writing heavy controllers
+- [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers)-like interface and conventions
 
 ## Problem
-
-Let's say we have a API create endpoint that takes json that looks something like
+Let's say we have an API with an endpoint that takes this JSON:
 
 ```json
 {
@@ -23,7 +24,7 @@ Let's say we have a API create endpoint that takes json that looks something lik
 }
 ```
 
-that goes into a flat DishReview model that looks like
+But this goes into a flat DishReview model:
 
 ```ruby
 t.belongs_to  :restaurant
@@ -37,11 +38,10 @@ t.string      :texture
 t.string      :smell
 ```
 
-what do we do?
+### Solution (No `Deserializer`)
+Permit some params, do some parsing and feed that into `DishReview.new`:
 
-Normally, we'd have some params we permit, do some parsing and feed those into `DishReview.new`, like
-
-``` ruby
+```ruby
 class DishReviewController < BaseController
 
   def create
@@ -93,30 +93,78 @@ class DishReviewController < BaseController
 end
 ```
 
-and that's fine, but kind of annoying, and you have to do this for every action. It makes the controllers heavy, hard to parse, fragile, and really do things that are no longer controller-y. 
+#### What's up with that?
+- You have to do this for every action
+- Controllers are obese, hard to parse and fragile
+- Controllers are doing non-controller-y things
+
+### Solution (With `Deserializer`)
+`DishReviewDeserializer`:
+
+```ruby
+module MyApi
+  module V1
+    class DishReviewDeserializer < Deserializer::Base
+      attributes  :restaurant_id
+                  :user_id
+                  :description
+
+      attribute   :name, key: :dish_name
+
+      has_one :ratings, :deserializer => RatingsDeserializer
+
+      def ratings
+        object
+      end
+
+    end
+  end
+end
+```
 
-So what we have here is a wrapper that lets us get away from polluting the controller with all of this parsing and lets us build deserializers that look very much like our serializers. 
+`RatingsDeserializer`:
 
-## Usage
+```ruby
+module MyApi
+  module V1
+    class RatingsDeserializer < Deserializer::Base
 
-Deserializer acts and looks pretty mich identical to ActiveModel::Serializer. It has attributes, attribute, and the has_one association. It does not currently support has_many, as that's an odd thing for a write endpoint to support, but can easily be added. 
+      attributes  :taste,
+                  :color,
+                  :texture,
+                  :smell
+    end
+  end
+end
+```
 
-### Deserializer functions
+All of this allows your controller to be so very small:
 
-#### from_params
-`MyDeserializer.from_params(params)` created the json that your AR model will then consume. 
 ```ruby
-@review = DishReview.new( MyApi::V1::DishReviewDeserailzer.from_params(params) )
+class DishReviewsController < YourApiController::Base
+  def create
+    @review = DishReview.new( MyApi::V1::DishReviewDeserailzer.from_params(params) )
+
+    if @review.save
+      # return review
+    else
+      # return sad errors splody
+    end
+  end
+
+  # RUD
+end
 ```
 
-#### permitted_params
-If you're using strong params, this lets you avoid having multiple definitions in fragile arrays. Just call ` MyDeserailzer.permitted_params` and you'll have the full array of keys you expect params to have.
+#### What's up with that?
+- Un-pollutes controllers from all the parsing
+- Builds deserializers that look like our serializers
 
-### Deserializer Definition
-To define a deserializer, you inherit from `Deserializer::Base` and define it in much the same way you would an `ActiveModel::Serializer`. 
+## Definition
+Inherit from `Deserializer::Base` and define it in much the same  way you would an [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
 
-#### attributes
-This is straight 1:1 mapping from params to the model, so 
+### attributes
+Use `attributes` for straight mapping from params to the model:
 
 ```ruby
 class PostDeserializer < Deserializer::Base
@@ -124,31 +172,70 @@ class PostDeserializer < Deserializer::Base
               :body
 end
 ```
-with params `{"title" => "lorem", "body" => "ipsum"}`, will give you a hash of `{title: "lorem", body: "ipsum"}`.
 
-#### attribute
-`attribute` is the singular version of `attributes`, but like `ActiveModel::Serializer` it can take a `:key`
+```ruby
+# Example params
+{
+    "title" => "lorem",
+    "body"  => "ipsum"
+}
+# Resulting hash
+   {
+     title: "lorem",
+     body: "ipsum"
+   }
+```
+
+### attribute
+Allows the following customizations for each `attribute` 
+#### :key
+
 ```ruby
 class PostDeserializer < Deserializer::Base
   attribute :title, ignore_empty: true
-  attribute :body, key: :text
+  attribute :body, key: :content
 end
 ```
-It is symmetric with `ActiveModel::Serializer`, so that :text is what it will get in params, but :body is what it will insert into the result. 
 
-For example with params of `{"title" => "lorem", "text" => "ipsum"}` this desrerializer will produce `{title: "lorem", body: "ipsum"}`.
+`:content` here is what it will get in params while `:body` is what it will be inserted into the result.
+
+```ruby
+# Example params
+{
+    "title"   => "lorem",
+    "content" => "ipsum"
+}
+# Resulting hash
+  {
+    title: "lorem",
+    body: "ipsum"
+  }
+```
+
+#### :ignore_empty
+While `Deserializer`'s default is to pass all values through, this option will drop any key with `false`/`nil`/`""`/`[]`/`{}` values from the result.
 
-`ignore_empty` is an option to ignore `false`/`nil`/`""`/`[]`/`{}` values that may come into the deserializer. By defualt it will pass the value through. With this option, it will drop the key from the result, turning `{"title" => "", "text" => nil}` into `{}`
+```ruby
+# Example params
+{
+    "title" => "",
+    "text"  => nil
+}
+# Resulting hash
+  {}
+```
 
-`convert_with` allows the deserializer to deserialize and convert a value at the same time. For example, if we have a `Post` model that looks like
+#### :convert_with
+Allows deserializing and converting a value at the same time. For example:
 
-```ruby 
+```ruby
 class Post < ActiveRecord::Base
   belongs_to :post_type # this is a domain table
 end
 ```
 
-and we serialize with 
+If we serialize with
+
 ```ruby
 class PostSerializer < ActiveModel::Serializer
   attribute :type
@@ -159,13 +246,13 @@ class PostSerializer < ActiveModel::Serializer
 end
 ```
 
-Then, when we if we get a symbolic name from the controller, but want to work with an id in the backend, we can do something like:
+Then, when we get a symbolic name from the controller but want to work with an id in the backend, we can:
 
 ```ruby
 class PostDeserializer < Deserializer::Base
   attribute :title, ignore_empty: true
   attribute :body
-  attribute :post_type_id, key: type, convert_with: to_type_id
+  attribute :post_type_id, key: :type, convert_with: to_type_id
 
   def to_type_id(value)
     Type.find_by_symbolic_name.id
@@ -173,13 +260,25 @@ class PostDeserializer < Deserializer::Base
 end
 ```
 
-which would take the params `{"title" => "lorem", "body" => "ipsum", "type" => "BLAGABLAG"}` and produce `{title: "lorem", body: "ipsum", post_type_id: 1}`
+```ruby
+# Example params
+{
+    "title" => "lorem",
+    "body"  => "ipsum",
+    "type"  => "BLAGABLAG"
+}
+# Resulting hash
+  {
+    title: "lorem",
+    body: "ipsum",
+    post_type_id: 1
+  }
+```
 
+### has_one
+`has_one` association expects a param and its deserializer:
 
-#### has_one
-NOTE: This is the only association currently supported by `Deserializer`.
-`has_one` expects the param and its deserializer.
-```ruby 
+```ruby
 class DishDeserializer < Deserializer::Base
   # probably other stuff
   has_one :ratings, deserializer: RatingsDeserializer
@@ -190,10 +289,27 @@ class RatingsDeserializer < Deserializer::Base
               :smell
 end
 ```
-So for params `{"ratings" => {"taste" => "bad", "smell" => "good"}}` you would get `{ratings: {taste: "bad", smell: "good"}}`
 
-#### Overriding Attribute Methods
-So let's say in the example above, your internal representation of ratings inside `Dish` is actually called `scores`, you can do
+```ruby
+# Example params
+{
+    "ratings" => {
+        "taste" => "bad",
+        "smell" => "good"
+    }
+}
+# Resulting hash
+  {
+    ratings: {
+      taste: "bad",
+      smell: "good"
+    }
+  }
+```
+
+#### Deserialize into a Different Name
+In the example above, if `ratings` inside `Dish` is called `scores` in your ActiveRecord, you can:
+
 ```ruby
 class DishDeserializer < Deserializer::Base
   has_one :ratings, deserializer: RatingsDeserializer
@@ -203,9 +319,26 @@ class DishDeserializer < Deserializer::Base
   end
 end
 ```
-which will give you `{scores: {taste: "bad", smell: "good"}}` for params `{"ratings" => {"taste" => "bad", "smell" => "good"}}`
 
-or, if you want to deserialize `ratings` into your `dish` object, you can use `object`
+```ruby
+# Example params
+{
+    "ratings" => {
+        "taste" => "bad",
+        "smell" => "good"
+    }
+}
+# Resulting hash
+  {
+    scores: {
+      taste: "bad",
+      smell: "good"
+    }
+  }
+```
+
+#### Deserialize into Parent Object
+To deserialize `ratings` into the `dish` object, you can use `object`:
 
 ```ruby
 class DishDeserializer < Deserializer::Base
@@ -216,9 +349,17 @@ class DishDeserializer < Deserializer::Base
   end
 end
 ```
-which will give you `{taste: "bad", smell: "good"}` for params `{"ratings" => {"taste" => "bad", "smell" => "good"}}`
 
-or you can deserialize into another subobject by doing
+```ruby
+# Resulting hash
+  {
+    taste: "bad",
+    smell: "good"
+  }
+```
+
+#### Deserialize into a Different Sub-object
+
 ```ruby
 class DishDeserializer < Deserializer::Base
   has_one :colors,  deserializer: ColorsDeserializer
@@ -229,99 +370,126 @@ class DishDeserializer < Deserializer::Base
   end
 end
 ```
-which, given params 
-```
-{ 
-  "ratings" => 
-    { 
+
+Given params:
+
+```ruby
+# Example params
+{
+  "ratings" =>
+    {
       "taste" => "bad",
       "smell" => "good"
-    }, 
-  "colors" => 
-    { 
+    },
+  "colors" =>
+    {
       "color" => "red"
     }
 }
+# Resulting hash
+  {
+    ratings: {
+      taste: "bad",
+      smell: "good",
+      color: "red"
+    }
+  }
 ```
-, will give you `{ratings: {taste: "bad", smell: "good", color: "red"}}`
 
-### Example
+### has_many
+Not supported as it's an odd thing for a write endpoint to support, but can easily be added.
+
+### nests
+Sometimes you get a flat param list, but want it to be nested for `updated_nested_attributes`
 
-So the example above will combine all of those to look like 
+If you have 2 models that look like
 
 ```ruby
-module MyApi
-  module V1
-    class DishReviewDeserializer < Deserializer::Base
-      attributes  :restaurant_id
-                  :user_id
-                  :description
+class RestaurantLocation
+  belongs_to :address
+  # t.string :name
+end
 
-      attribute   :name, key: :dish_name
+# where Address is something like
+t.string      :line_1
+t.string      :line_2
+t.string      :city
+t.string      :state
+```
 
-      has_one :ratings, :deserializer => RatingsDeserializer
+And you want to update them at the same time, as they're closely tied, `nests` lets you define
 
-      def ratings
-        object
-      end
+```ruby
+class ResaturantLocationDeserializer < Deserializer::Base
+  attribute :name
 
-    end
-  end
+  nests :address, deserializer: AddressDesrializer
 end
-```
 
-where RatingsDeserializer looks like
+class AddressDeserializer
+  attributes  :line_1,
+              :line_2,
+              :city,
+              :state
+end
+```
+And now you can take a single block of json
 
 ```ruby
-module MyApi
-  module V1
-    class RatingsDeserializer < Deserializer::Base
+# Example params into restaurant_location endpoint
+{
+  "name"    => "Little Caesars: Et Two Brute",
+  "line_1"  => "2 Brute St.",
+  "city"    => "Seattle",
+  "state"   => "WA"
+}
+
+# Resulting hash
+{
+     name: "Little Caesars: Et Two Brute",
+  address: {
+      line_1: "2 Brute St",
+        city: "Seattle",
+       state: "WA"
+  }
+}
 
-      attributes  :taste,
-                  :color,
-                  :texture,
-                  :smell
-    end
-  end
-end
 ```
 
-All of this allows your controller to be so very small, like
 
-```ruby
-class DishReviewsController < YourApiController::Base
-  def create
-    @review = DishReview.new( MyApi::V1::DishReviewDeserailzer.from_params(params) )
 
-    if @review.save
-      # return review
-    else
-      # return sad errors splody
-    end
-  end
+## Functions
+### from_params
+`MyDeserializer.from_params(params)` creates the JSON that your AR model will then consume.
 
-  # RUD
-end
+```ruby
+@review = DishReview.new( MyApi::V1::DishReviewDeserailzer.from_params(params) )
 ```
 
-## Installation
+### permitted_params
+Just call `MyDeserailzer.permitted_params` and you'll have the full array of keys you expect params to have.
 
+## Installation
 Add this line to your application's Gemfile:
 
-    gem 'deserializer'
+```
+gem 'deserializer'
+```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install deserializer
-
+```
+$ gem install deserializer
+```
 
 ## Contributing
-
-1. Fork it ( https://github.com/[my-github-username]/deserializer/fork )
+1. Fork it ( [https://github.com/[my-github-username]/deserializer/fork](https://github.com/[my-github-username]/deserializer/fork) )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/deserializer.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |s|
   s.test_files    = s.files.grep(%r{^(test|s|features)/})
   s.require_paths = ["lib"]
 
+  s.add_dependency "activesupport"
+
   s.add_development_dependency "bundler", "~> 1.6"
   s.add_development_dependency "rake"
 end

data/lib/deserializer.rb

@@ -1,6 +1,9 @@
 require "deserializer/version"
+require 'active_support'
+require 'active_support/concern'
 
 module Deserializer
+  autoload :Associatable, 		'deserializer/associatable'
   autoload :Base,               'deserializer/base'
   autoload :DeserializerError,  'deserializer/deserializer_error'
 end

data/lib/deserializer/associatable.rb

@@ -0,0 +1,38 @@
+module Deserializer
+  module Associatable
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        def has_one( target, opts = {})
+          deserializer = opts[:deserializer]
+
+          unless deserializer
+            raise DeserializerError, class: self, message: "has_one associations need a deserilaizer" 
+          end
+
+          self.attrs[target] = { attr: nil, deserializer: deserializer }
+        end
+
+        def has_many(*args)
+          raise DeserializerError, class: self, message: "has_many is intentionally unsupported."
+        end
+
+        def belongs_to(*args)
+          raise DeserializerError, class: self, message: "belongs_to is unsupported."
+        end
+
+        def nests(target, opts = {})
+          deserializer = opts[:deserializer]
+
+          unless deserializer
+            raise DeserializerError, class: self, message: "nested associations need a deserilaizer" 
+          end
+
+          self.nested_attrs ||= {}
+          self.nested_attrs[target] = { deserializer: deserializer }
+        end
+      end
+    end
+  end
+end

data/lib/deserializer/base.rb

@@ -1,7 +1,11 @@
 module Deserializer
   class Base
+
+    ## has_one, nested, etc associations
+    include Deserializer::Associatable
+
     class << self
-      attr_accessor :attrs
+      attr_accessor :attrs, :nested_attrs
     
       # deserializer interface functions
 
@@ -18,24 +22,6 @@ module Deserializer
         self.attrs[key] = {attr: attr, options: options}
       end
 
-      def has_one( target, opts = {})
-        deserializer = opts[:deserializer]
-
-        unless deserializer
-          raise DeserializerError, class: self, message: "has_one associations need a deserilaizer" 
-        end
-
-        self.attrs[target] = {attr: nil, deserializer: deserializer}
-      end
-
-      def has_many(*args)
-        raise DeserializerError, class: self, message: "has_many is currently unsupported."
-      end
-
-      def belongs_to(*args)
-        raise DeserializerError, class: self, message: "belongs_to is currently unsupported."
-      end
-
       # deserializer usage functions
 
       def from_params( params = {} )
@@ -57,7 +43,7 @@ module Deserializer
 
         # this checks if the object_key is a class that inherits from Deserializer
         if object_key[:deserializer]
-          deseralize_nested(param_key, object_key[:deserializer])
+          deseralize_association(param_key, object_key[:deserializer])
         else
           attribute = object_key[:attr]
           options   = object_key[:options]
@@ -65,6 +51,11 @@ module Deserializer
           assign_value attribute, params[param_key], options
         end
       end
+
+      self.class.nested_attrs ||= {}
+      self.class.nested_attrs.each do |target, options|
+        deserialize_nested target, options[:deserializer]
+      end
       object
     end
 
@@ -73,7 +64,6 @@ module Deserializer
     attr_accessor   :params
     attr_writer     :object
 
-
     def initialize( object = {}, params = {})
       unless params
         raise DeserializerError, class: self.class, message: "params cannot be nil"
@@ -83,7 +73,17 @@ module Deserializer
       self.object = object
     end
 
-    def deseralize_nested(association, deserializer)
+    def deseralize_association(association, deserializer)
+      # check for method defining the target object (something, in the example below)
+      #
+      # class ExampleDeserializer < Deserializer::Base
+      #   has_one :something, deserializer: SomethingDeserializer
+      #   
+      #   def something
+      #     object
+      #   end
+      # end
+
       if self.respond_to? association
         
         target = self.send( association )
@@ -98,6 +98,11 @@ module Deserializer
       deserializer.new( target, params[association] ).deserialize
     end
 
+    def deserialize_nested( target, deserializer )
+      target = object[target] ||= {}
+      deserializer.new( target, params ).deserialize
+    end
+
     def assign_value( attribute, value, options = {} )
       if options[:ignore_empty] && empty?(value)
         return

data/lib/deserializer/version.rb

@@ -1,3 +1,3 @@
 module Deserializer
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/test/lib/deserializers.rb

@@ -110,4 +110,16 @@ class NillableConversionDeserializer < Deserializer::Base
     range_array = Array(value)
     (range_array[0]..range_array[-1])
   end
+end
+
+class NestedDeserializer < Deserializer::Base
+  attribute :name, key: :attr_1
+  attribute :attr_2
+end
+
+class NestableDeserializer < Deserializer::Base
+  attributes  :id,
+              :attr_1
+
+  nests :nested_object, deserializer: ::NestedDeserializer
 end

data/test/unit/deserializer_test.rb

@@ -142,4 +142,17 @@ class DeserializerTest < Minitest::Test
 
     assert_equal expected, NillableConversionDeserializer.from_params( params )
   end
+
+  def test_using_requires_deserializer
+     assert_raises Deserializer::DeserializerError do
+      BasicDeserializer.nests :splosion
+    end
+  end
+
+  def test_supports_using
+    params   = { id: 1, attr_1: "blah", attr_2: "something" }
+    expected = { id: 1, attr_1: "blah", nested_object: { name: "blah", attr_2: "something" } }
+
+    assert_equal expected, NestableDeserializer.from_params( params )
+  end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: deserializer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Greg Orlov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-21 00:00:00.000000000 Z
+date: 2015-12-03 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -54,6 +68,7 @@ files:
 - Rakefile
 - deserializer.gemspec
 - lib/deserializer.rb
+- lib/deserializer/associatable.rb
 - lib/deserializer/base.rb
 - lib/deserializer/deserializer_error.rb
 - lib/deserializer/version.rb
@@ -90,4 +105,3 @@ test_files:
 - test/minitest_helper.rb
 - test/unit/deserializer_error_test.rb
 - test/unit/deserializer_test.rb
-has_rdoc: