capsula 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c534b9fef1cf66293f27706a7399215013ca7d41f58b3fd7bbf6e1f4990bc0a8
-  data.tar.gz: 16af229a6c5155c34e8fc4e91eac9911fae50c6cfd29e5b102aa14ebae28a07d
+  metadata.gz: c079ef240a2cfdd558fdf3edffa7987476f278ade0831c55947011fac809ba9b
+  data.tar.gz: 8d99d06ef13427f10e8bab16a2ba813a7621c65e1348deae30dd3e2d8e253591
 SHA512:
-  metadata.gz: 3480eb2df25870f7e9fd507847897cdc8cee3037bbef3c25312ef822218bf9ac54e34ecb4e7acfbf5609bc18334300fb8b71f799b5ca107989b14e17368aef12
-  data.tar.gz: 2240b2987901d94a39d5407f0b4caa9ad943987d0e0bfe1ae4433cb1dbed18673977a13f92eaa65a4ae14c4dd52c53a70e68b43c0501e3a98ad3f636986d5643
+  metadata.gz: 2e9519cd42c384e75c56ec4e342d3506da9ee0ffa83a231a36eb82d87b324bcf637bc0112c594778fe1a1c22723acefe4eb2122d824a69ca639e25a3300bd9e9
+  data.tar.gz: e5edde7d165a6eb1f075222d6be927c98c4c39b86af12765eb8abebc4ea03eb8fdf9db8fb5308b18d22aad49a09ed143e96f34ff37346db4027cc3aa8aeef466

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capsula (0.0.2)
+    capsula (0.0.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,42 +1,97 @@
 # Capsula
-The tool for encapsulating (preloading, including) related objects into **any** object.
+The tool for preloading related objects into **any** object to prevent N+1 queries.
 
-## How to use:
-
-Add to Gemfile:
+## INSTALL
 
 ```
 gem 'capsula'
 ```
 
-Then:
+## USE
 
 ```ruby
-starships = <get_your_space_fleet>
+require 'capsula'
+
+# our objects
+$cars = [ {name: 'A', brand_id: 3}, {name: 'B', brand_id: 1}, {name: 'C', brand_id: 1} ]
+$brands = [ {id: 1, name: 'Ferrari'}, {id: 2, name: 'Lamborghini'}, {id: 3, name: 'Rolls-Royce'} ]
+
+# let's preload cars with brands
+
+# our capsula-preloader
+class CarPreloader < Capsula::Base
+  plan_for :brand,
+    src_key: -> (car) { car[:brand_id] },
+    dst_key: -> (brand) { brand[:id] },
+    dst_loader: -> (ids, opt) { $brands.select { |b| ids.include?(b[:id]) } }
+end
+
+# ok, preload!
+$cars = CarPreloader.new($cars).plans(:brand).encapsulate
 
-starships = StarshipsEncapsulator.new(starships).plans(
-  :fuel, :oxygen, :food, { spaceman: [:space_suit] }
+$cars
+# => [{:name=>"A", :brand_id=>3}, {:name=>"B", :brand_id=>1}, {:name=>"C", :brand_id=>1}]
+
+# hm... where is brands?
+
+$cars.first.brand
+# => {:id=>3, :name=>"Rolls-Royce"}
+
+$cars[0].brand
+# => {:id=>3, :name=>"Rolls-Royce"}
+$cars[1].brand
+# => {:id=>1, :name=>"Ferrari"}
+$cars[2].brand
+# => {:id=>1, :name=>"Ferrari"}
+
+# so, source objects leave untouched, but was wrapped for methods interception
+```
+
+### ActiveRecord case:
+
+```ruby
+cars = Cars.where(id: [1,2,3]).to_a
+
+cars = CarPreloader.new(cars).plans(
+  :fuel, :food, { driver: [:car_keys, :sunglasses] }
 ).encapsulate
 
-# Now let's get a suit for our spaceman:
-starships.first&.spaceman&.space_suit
-=> <awesome space suit>
-# no actual action was triggered,
+cars.first.driver.car_keys
+=> <car_keys>
+# no actual action (any SQL query) was triggered,
 # immediate result was received from Capsula's wrapper
 ```
 
-Let's see how `StarshipsEncapsulator` looks:
+Let's see how `CarPreloader` looks:
 
 ```ruby
 class StarshipsEncapsulator < Capsula::Base
-  plan_for :fuel,
-    src_key: :fuel_id,
-    dst_key: :id,
-    dst_loader: ->(ids,opt){ MyFuelStation.find_fuel_by_ids(ids) }
-    # Example loader for ActiveRecord model Fuel:
-    # dst_loader: ->(ids,opt){ Fuel.where(id: ids).includes(opt[:plans]).to_a }
-
-  # Plans for other relations...
+  plan_for :driver,
+    src_key: :driver_id, # it's default value, so can be skipped
+    dst_key: :id,        # it's default value, so can be skipped
+    # Example loader for ActiveRecord model Driver:
+    dst_loader: -> (ids, opt) {
+        Driver.where(id: ids).includes(opt[:plans]).to_a
+      }
+
+  # # Plans for other relations:
+  # plan_for :fuel, ...
+  # plan_for :food, ...
+end
+```
+
+### has_many example
+
+You can use custom encapsulator, but stantard encapsulator understand you if dst_key be placed inside array:
+
+```ruby
+class Sea < Capsula::Base
+  plan_for :crabs,
+    src_key: :name,
+    dst_key: [:sea_name], # key inside array signals about has_many relation
+    dst_loader: -> (sea_names, opt) {
+        Crab.where(sea_name: sea_names).includes(opt[:plans]).to_a
+      }
 end
 ```
 
@@ -44,7 +99,7 @@ end
 
 **default values:**
 
-Definition for `src_key` and `dst_key` can be skipped if they values are `:fuel_id` (`<key_name>_id`) and `:id`
+Definition for `src_key` and `dst_key` can be skipped if they values are `:driver_id` (`<key_name>_id`) and `:id`
 
 **lambdas:**
 
@@ -94,12 +149,13 @@ class CustomLoader
   # This method is triggered by Capsula
   def collect_ids_and_load_relations
     ids = @items.map{ |i| i.fuel_id }
-    @store = Fuel.where(id: ids).to_a
+    preloads = Fuel.where(id: ids).to_a
+    @store = preloads.index_by(&:id)
   end
 
   # This method is calling by Capsula during encapsulation
   def get_preloads_for_object starship
-    @store.find { |fuel| starship.fuel_id == fuel.id }
+    @store[starship.fuel_id]
   end
 end
 

data/capsula.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name        = 'capsula'
-  s.version     = '0.0.3'
-  s.date        = '2019-02-04'
+  s.version     = '0.0.4'
+  s.date        = '2019-05-29'
   s.summary     = 'Encapsulating tool'
   s.description = 'The tool for encapsulating (preloading, including) related objects'
   s.authors     = ['Rodion V']

data/lib/capsula/encapsulator.rb

@@ -108,8 +108,14 @@ module Capsula
       col =
         if ids.any?
           preloads = dec[:dst_loader].call(ids,opt)
-          # build hash: {id1 => Obj1, ..., idN => ObjN }
-          index_array_by(preloads) { |el| get_value(el, dec[:dst_key]) }
+          dst_key = dec[:dst_key]
+          if dst_key.is_a?(Array)
+            # build hash: {id1 => [Obj1, ...], idN => [ObjN] }
+            preloads.group_by { |o| get_value(o, dst_key.first) }
+          else
+            # build hash: {id1 => Obj1, ..., idN => ObjN }
+            index_array_by(preloads) { |el| get_value(el, dst_key) }
+          end
         else
           {}
         end
@@ -130,12 +136,16 @@ module Capsula
     def native_encapsulation plan_key, preloaded_collection, declaration
       col = preloaded_collection
       dec = declaration
+      is_dst_key_array = dec[:dst_key].is_a?(Array)
 
       @items.each do |i|
         src_id = get_value(i, dec[:src_key])
 
         val =
-          if src_id.is_a?(Array)
+          if is_dst_key_array
+            # src has many dst
+            col[src_id] || []
+          elsif src_id.is_a?(Array)
             # if object has many links to related objects (Array)
             col.values_at(*src_id)
           else
@@ -151,6 +161,8 @@ module Capsula
       case key_or_lambda
       when ::Symbol, ::String
         _object_.send(key_or_lambda)
+      when ::Array
+        _object_.send(key_or_lambda[0])
       when ::Proc
         key_or_lambda.call(_object_)
       else

data/spec/capsula_spec.rb

@@ -2,10 +2,11 @@ require 'capsula'
 
 RSpec.describe Capsula do
   let(:klass){ Class.new(Capsula::Base) }
-  let(:a)    { Struct.new(:b_id) }
-  let(:b)    { Struct.new(:id) }
 
   describe 'User can' do
+    let(:a) { Struct.new(:b_id) }
+    let(:b) { Struct.new(:id) }
+
     it 'declare new encapsulation plan' do
       klass.plan_for(:b, src_key: :b_id, dst_key: :id, dst_loader: ->(i,o){})
       plans = klass.instance_variable_get('@plans_declarations')
@@ -82,7 +83,32 @@ RSpec.describe Capsula do
       expect(objects.first).to be_a(Capsula::Wrapper)
       expect(objects.first.b.id).to be == objects.first.b_id
     end
+  end
+
+  describe 'has_many plan' do
+    let(:a) { Struct.new(:id) }
+    let(:b) { Struct.new(:a_id) }
+
+    it 'working' do
+      b_store = [1,2,2,3].map { |a_id| b.new(a_id) }
+      klass.plan_for(
+        :bs,
+        src_key: :id,
+        dst_key: [:a_id],
+        dst_loader: ->(ids,opt){ b_store.select { |b| ids.include?(b.a_id) } }
+      )
 
+      as = [2,3,4].map { |id| a.new(id) }
+      as = klass.new(as).plans(:bs).encapsulate
+
+      expect(as[0]).to respond_to(:bs)
+      expect(as[0]).to be_a(Capsula::Wrapper)
+      expect(as[0].bs.count).to eq(2)
+      expect(as[1].bs.count).to eq(1)
+      expect(as[2].bs.count).to eq(0)
+      expect(as[0].bs[0].a_id).to eq(as[0].id)
+      expect(as[1].bs[0].a_id).to eq(as[1].id)
+    end
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capsula
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Rodion V
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-04 00:00:00.000000000 Z
+date: 2019-05-29 00:00:00.000000000 Z
 dependencies: []
 description: The tool for encapsulating (preloading, including) related objects
 email: rodion.v@devaer.com