hash19 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ff2d798a32b0fb67c383d53b88546b11acb8ce9d
-  data.tar.gz: ad33dffbd106aa49d391743f63943011baf81b90
+  metadata.gz: 8d4abf9fa415283f0a656fd345f9bd33cc99bc59
+  data.tar.gz: 99a02257f4412c560e9efa21b01c1152366de9db
 SHA512:
-  metadata.gz: 999a9eee4711d4d188155f2642a327c2dc02935e0e155529719b32749c1fcb48fa3e9997c9c08fd1584bd338f49d59ffcddaa0198cba68faf7b274f17a72ee1f
-  data.tar.gz: c9a1b4b182208b75970e0bb4d40bcf2f0ded531549b9ae231f3071e7c4ce9f6a948dd48cf6fa7a28a99f8604134e82b2c19e2458c5276964b7bc5dd1360145e2
+  metadata.gz: f769a3aaaec08daeb22c90867935d858fd7fb31e3ad6d26cc81ca5be2acb90b1c39fc0ac7467a2a19cb9b0d23b54550d07928c26e0d096dff52d9cf6edf2dbad
+  data.tar.gz: f88e1b86c8e5309d79e8d591114fab773bcacf6a647d5c01d6b8060606ba121f0a7761b998bf2c792c21457cfe323dfc4930da2a9901a59fa53bc5576c63c665

data/README.md

@@ -1,11 +1,21 @@
 # Hash19
-
 [![Build Status](https://travis-ci.org/rcdexta/hash19.svg)](https://travis-ci.org/rcdexta/hash19)
 
-TODO: Write a gem description
+![Hash-19](https://s3-us-west-1.amazonaws.com/rcdexta/hash-19-droid.png)
 
-## Installation
+>*Hash-19 is as an assassin droid in the Star Wars Universe. These are durasteel drones uploaded with only the most archaic kill programs* <sup>[Wookieepedia]</sup>
+
+Ahem.. Ahem.. So about this gem itself.. When I was writing an aggregation API that had to talk to multiple services each with their own REST end-points and JSON schema, when mashing up multiple hashes and transforming it to a structure acceptable to the consumer, I ended up writing lot of boiler plate code. I could see patterns and there was clearly scope for optimisation.
 
+Hash19 is an attempt at offering a DSL to tame the JSON manipulation and help in dealing with common use-cases. The features include
+
+* whitelisting attributes
+* attribute aliasing and keying
+* `has_one` and `has_many` associations 
+* lazy loading associations via triggers
+* mass injection of associations using bulk APIs
+
+## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -20,14 +30,174 @@ Or install it yourself as:
 
     $ gem install hash19
 
+### One example for all
+```ruby
+class Jedi
+    include Hash19
+    attributes :name, :saber, :padawan_id
+    attribute :master, key: :trained_by
+    has_one :padawan, using: :padawan_id, trigger: ->(id) { Padawan.find id }
+    has_many :killings
+end
+
+class Padawan
+    include Hash19
+    attributes :id, :name
+    def find(id)..end #implementation hidden
+    def find_all(ids)..end #implementation hidden
+end
+
+json = '[{"name": "Anakin Skywalker", "saber": "Single Blade Blue",  "trained_by": "Obi Wan",
+         "padawan": {"id": 201, "name": "Ahsoka Tano"}},
+        {"name": "Mace Windu", "saber": "Single Blade Violet", "padawan_id": 132, "trained_by": "Yoda"}]'
+        
+jedis = JSON.parse(json)    
+Jedi.new(jedis.first).to_h #{"name"=>"Anakin Skywalker", "saber"=>"Single Blade Blue", "master"=>"Obi Wan",
+                           #"padawan"=>{"id"=>201, "name"=>"Ahsoka Tano"}}
+                           
+Jedi.new(jedis.last).to_h #{"name"=>"Mace Windu", "saber"=>"Single Blade Violet", "master"=>"Yoda",
+                           #"padawan"=>{"id"=>132, "name"=>"Depa Billaba["}}
+
+```
+All aspects of the code are explained with detailed examples below. This gives a quick snapshot of what the gem can do. Ergo...
+* the attributes `name`, `saber` and `padawan_id` have been whitelisted. Any other attribute in the JSON will be ignored
+* the attributes can have aliases in the actual JSON
+* there can be an inline relationship within the JSON with another entity. For example, each `Jedi` entity can contain a `padawan` object. If the association already exists, it will be transformed. This is true for the first Jedi in the example
+* If the association is not present in the JSON, it is lazy loaded. The first call to the attribute will call the trigger to fetch the association, if not present. In this case, for the second Jedi, a call `Padawan#find` will be triggered and the association fetched.
+
+Now, this immediately raises the question about firing multiple calls to Padawan#find when there are many entries without the association populated. And that's where injection is recommended:
+
+```ruby
+class Jedis
+    include Hash19 
+    contains :jedi
+    inject at: '$', using: :padawan_id, reference: :id, 
+           trigger: lambda { |ids| Padawan.find_all ids }, as: 'padawan'
+end
+```
+This is like a wrapper class for the Jedi collection. It collects all `padawan_ids` from the complete JSON, calls `Padawan#find_all` once, the bulk-api equivalent of `find`, with a list of ids and injects the content back to the main collection at appropriate places as defined by the json_path in `at`
+
 ## Usage
 
-TODO: Write usage instructions here
+To get started, include the Hash19 module in the target class and you are good.
+
+A detailed documentation of all features can be found below:
+
+###1. Whitelisting attributes
+```ruby
+ class SuperHero 
+	 include Hash19
+	 attributes :name, :strength
+	 attribute :universe, key: :comic
+ end
+ ```
+ Assume a JSON payload has many more attributes
+ ```json
+ [{"name": "Flash", "strength": "Speed", "last_seen": "never", "comic": "DC"},
+  {"name": "Magneto", "strength": "Magnetism Control", "first_seen": 1963, "comic": "Marvel"},
+  {"name": "Hulk", "strength": "Super Strength", "weakness": "temper", "comic": "Marvel"}]
+  ```
+  When this JSON is thrown at a Hash19 class...
+  ```ruby
+    payload = JSON.parse(json)
+    results = payload.map { |hash| SuperHero.new(hash).to_h }
+    print results #[{"name"=>"Flash", "strength"=>"Speed", "universe"=>"DC"},
+                  # {"name"=>"Magneto", "strength"=>"Magnetism Control", "universe"=>"Marvel"},
+                  # {"name"=>"Hulk", "strength"=>"Super Strength", "universe"=>"Marvel"}]
+  ```
+  Note that only the whitelisted attributes are accepted and keys can be aliased. The `to_h` method converts the native hash19 object into a ruby hash. 
+  
+###2. Still a hash
+The Hash19 object acts as a wrapper to Ruby Hash. All hash operations are supported by the wrapper. But, finally `to_h` should be called to retrieve the underlying hash.
+``` ruby
+ hero = SuperHero.new(name: "Flash", strength: "Speed", comic: "DC")
+ hero[:name] #Flash
+ hero[:nick_name] = "Scarlet Speedster"
+ hero.keys #["name", "strength", "universe", "nick_name"]
+ hero.to_h #{"name"=>"Flash", "strength"=>"Speed", "universe"=>"DC", "nick_name"=>"Scarlet Speedster"}
+```
+###3. Associations
+One-to-one and One-to-many relationships are supported. All associations are lazy loaded unless present directly in the root JSON.
+```ruby
+class Hashable
+    include Hash19
+end
+class SuperVillain < Hashable
+    attribute :name
+    has_many :minions
+    has_one :doctor
+end
+class Minion < Hashable
+  attributes :name, :sound
+end
+class Doctor < Hashable
+  attribute :name
+end
+```
+Now, a JSON of the following structure
+```json
+{"name": "Gru", "doctor": {"name": "Nefario"}, 
+"minions": [{"name": "Poppadom", "sound": "Weebaa"},{"name": "Gelato", "sound": "Ooojaa"}]
+```
+can be parsed with all associations loaded when calling `SuperVillain.new(json_as_hash)`
+
+If the parent JSON does not contain the associations and they are powered by separate API calls, we can specify triggers to load them.
+```ruby
+class SuperVillain < Hashable
+    attribute :name, doctor_id
+    has_one :doctor, using: :doctor_id, trigger: ->(id) { Error.find id }
+end
+```
+If you notice the trigger, the `using` parameter denotes the attribute to use to fetch the association and the lambda passed to `trigger` will be invoked to fetch the association. This is lazy loaded, in the sense when a call is made to `.doctor` or `.to_h`, the trigger is fired.
+
+###4. Bulk Injections
+
+Left to itself with associations, when the root JSON is a large collection with none of the associations populated in the first place, there will several triggers fired for each item in the collection. This is the HTTP equivalent of `N+1` in the ORM world. To avoid this, Hash19 supports association injections. Let's dive into an example:
+
+```ruby
+class SuperHeroes < Hashable
+    contains :super_heroes
+    inject at: '$', using: :weapon_id, reference: :id, trigger: lambda { |ids| Weapon.find_all ids }
+  end
+
+  class SuperHero < Hashable
+    attributes :name, :power, :weapon_id
+    has_one :weapon, using: :weapon_id, trigger: lambda { |id| Weapon.find id }
+  end
+
+  class Weapon < Hashable
+    attributes :name, :id
+    def find_all(ids)..end #calls bulk API across wire. Implementation hidden
+  end
+```
+If you notice, `SuperHeroes` is a wrapper class around `SuperHero`. This is the object equivalent of a JSON collection. The `inject` method will extract `weapon_id` from all items in the collection and call the `trigger` and put back the resultant entities joining `superhero.weapon_id` and `weapon.id`
+
+So, a json like below
+```json
+super_heroes = SuperHeroes.new([{name: 'iron man', power: 'none', weapon_id: 1},
+                                {name: 'thor', power: 'class 100', weapon_id: 2},
+                                {name: 'hulk', power: 'bulk', weapon_id: 3}])
+```
+
+will lead to one call to `Weapon#find_all` with params `[1,2,3]` to fetch all weapon details. And the final collection will be of the form:
+```ruby
+super_heroes.to_h #[{'name' => 'iron man', 'power' => 'none', 'weapon' => {'name' => 'jarvis', 'id' => 1}},
+                  #{'name' => 'thor', 'power' => 'class 100', 'weapon' => {'name' => 'hammer', 'id' => 2}},
+                  #{'name' => 'hulk', 'power' => 'bulk', 'weapon' => {'name' => 'hands', 'id' => 3}}
+```
+
+Note that `injection` always overrides the association trigger sinces the former is eager loaded and latter is lazy loaded thus avoiding the `N+1` calls.
+
+Please refer to the [tests](https://github.com/rcdexta/hash19/tree/master/spec/hash19) for more examples and documentation.
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/hash19/fork )
+1. Fork it ( https://github.com/rcdexta/hash19/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`)
 5. Create a new Pull Request
+
+
+  
+  

data/lib/hash19/resolvers.rb

@@ -21,10 +21,13 @@ module Hash19
                                             association.map { |hash| klass.send(:new, hash).to_h(lazy: true) }
                                           end
         else
-          puts "warning: Association:<#{name}> is not present in #{self.class.name}. Possible specify a trigger" unless opts[:trigger]
+          unless opts[:trigger]
+            puts "warning: Association:<#{name}> is not present in #{self.class.name}. Possible specify a trigger" 
+            next
+          end
           puts "warning: Key:<#{opts[:using]}> not present in #{self.class.name}. Cannot map association:<#{name}>" unless @hash19.has_key? opts[:using]
           if opts[:trigger] and @hash19.has_key? opts[:using]
-            @hash19[opts[:alias] || name] = LazyValue.new(-> { opts[:trigger].call(@hash19.delete(opts[:using])) }) if opts[:trigger]
+            @hash19[opts[:alias] || name] = LazyValue.new(-> { opts[:trigger].call(@hash19.delete(opts[:using])) }) 
           end
         end
       end
@@ -60,9 +63,9 @@ module Hash19
       full_class_name = self.class.name
       new_class = full_class_name.gsub(full_class_name.demodulize, assoc_name)
       new_class.split('::').inject(Object) do |mod, class_name|
-        if mod.const_defined?(class_name)
+        begin
           mod.const_get(class_name)
-        else
+        rescue NameError
           raise("Class:<#{new_class}> not defined! Unable to resolve association:<#{assoc_name.downcase}>")
         end
       end

data/lib/hash19/version.rb

@@ -1,3 +1,3 @@
 module Hash19
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

data/spec/hash19/core_spec.rb

@@ -43,8 +43,8 @@ describe Hash19::Core do
    end
 
    it 'should be able to assign attributes based on alias' do
-    test = Test2.new(actual: 1)
-    expect(test.to_h).to eq('fake' => 1)
+    test = Test2.new("actual" => 1, "d" => 2)
+    expect(test.to_h).to eq('fake' => 1, "d" => 2)
   end
 
   it 'should be able to use both attribute and attributes constructs' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash19
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - RC
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-14 00:00:00.000000000 Z
+date: 2014-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler