capsula 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de1e116a89071a460417f16918fbc8ea0871ba2217a3b513d90f76028ff789c0
+  data.tar.gz: d66bf5ca919d2df33b664b5e50d9dab8afd3866a115ce47ab5e458335610d6fc
+SHA512:
+  metadata.gz: 9919c5c93000fa52a3615c41bb579ca202be4805b7d879219b59cb0b941ed214b07bf5d260ae5c3775bd0494d3c4abe808b92fb510942cc277243a575bde7dd8
+  data.tar.gz: d467d3cadada0ffb8cf7cb7ccc86b32b683a30e97b4a3aab079df1d101583a57c934673553a824544359011c0cdefa1fff2d2969997288a16dbaaf7fe54194d2

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+gemspec
+
+group :development do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-bundler'
+  gem 'rb-readline'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'simplecov', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,85 @@
+PATH
+  remote: .
+  specs:
+    capsula (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    ffi (1.10.0)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-bundler (2.2.1)
+      bundler (>= 1.3.0, < 3)
+      guard (~> 2.2)
+      guard-compat (~> 1.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    json (2.1.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.10.0)
+      ffi (~> 1.0)
+    rb-readline (0.5.5)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    thor (0.20.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  capsula!
+  guard
+  guard-bundler
+  guard-rspec
+  rb-readline
+  rspec
+  simplecov
+
+BUNDLED WITH
+   1.16.6

data/Guardfile

@@ -0,0 +1,10 @@
+guard :rspec, cmd: 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Rodion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Capsula
+The tool for encapsulating (preloading, including) related objects into **any** object.
+
+## How to use:
+
+```ruby
+starships = <get_your_space_fleet>
+
+StarshipsEncapsulator.new(starships).plans(
+  :fuel, :oxygen, :food, { spaceman: [:space_suit] }
+).encapsulate
+
+# Now let's get a suit for our spaceman:
+starships.first&.spaceman&.space_suit
+=> <awesome space suit> # Capsula's wrapper answers
+```
+
+Let's see how `StarshipsEncapsulator` 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...
+end
+```
+Definition for `src_key` and `dst_key` can be skipped if they values are `:fuel_id` (`<key_name>_id`) and `:id`
+
+
+Also, for key-definition can be used lambdas:
+
+```ruby
+src_key: ->(o){ o.some_hash_data.fetch(:fuel_id, default: 'A-95') }
+dst_key: ->(o){ o.extact_fuel_id_from_octane_number }
+```
+
+## How it works:
+
+All objects is wrapping into special transparent wrapper which
+translate all methods to wrapped object, except methods-names which was used for encapsulating before:
+
+```ruby
+StarshipsEncapsulator.new(starships).plan(:fuel, :oxygen).encapsulate
+starships.first.oxygen
+=> <oxygen> # instant response, because already present in Capsula
+```
+
+Rest methods transparently sending to wrapped object:
+
+```ruby
+starships.first.food
+=> <pizza> # returns to Mothership and cook pizza
+```
+
+## Custom encapsulators (dst_loaders):
+For difficult preloading logic can be used custom loader:
+
+```ruby
+class CustomLoader
+	def initialize items:, opt: {}
+		@items = items; @opt = opt; @store = [];
+	end
+
+	# 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
+	end
+
+	# This method is calling by Capsula during encapsulation
+	def get_preloads_for_object starship
+		@store.find { |fuel| starship.fuel_id == fuel.id }
+	end
+end
+
+
+class StarshipsEncapsulator < Capsula::Base
+  plan_for :fuel, delegate_to: CustomLoader
+end
+```
+
+## Contributing
+
+* Fork the project.
+* Run `bundle install`
+* Run `bundle exec guard`
+* Make your feature addition or bug fix.
+* Add tests for it. This is important.
+* Send me a pull request.

data/capsula.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name        = 'capsula'
+  s.version     = '0.0.2'
+  s.date        = '2019-02-04'
+  s.summary     = 'Encapsulating tool'
+  s.description = 'The tool for encapsulating (preloading, including) related objects'
+  s.authors     = ['Rodion V']
+  s.email       = 'rodion.v@devaer.com'
+  s.homepage    = 'https://github.com/brlo/capsula'
+  s.license     = 'MIT'
+
+  all_files     = `git ls-files`.split("\n")
+  test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.files         = all_files - test_files
+  s.test_files    = test_files
+  s.require_paths = ['lib']
+end

data/lib/capsula.rb

@@ -0,0 +1,3 @@
+require 'capsula/wrapper'
+require 'capsula/encapsulator'
+require 'capsula/base'

data/lib/capsula/base.rb

@@ -0,0 +1,62 @@
+module Capsula
+  class Base
+
+    ##
+    # Base class for inheritence when creating new Encapsulators
+    #
+
+    def initialize items
+      @items = items
+    end
+
+    def plans *keys
+      @keys = keys.flatten.compact.uniq
+      self
+    end
+
+    def encapsulate
+      Encapsulator.new(
+        items: @items,
+        declarations: self.class.merged_plans_declarations,
+        keys: @keys
+      ).preload_and_encapsulate
+    end
+
+    class << self
+
+      # DSL method
+      def plan_for relation_key, **opt
+        add_to_plans_declaration relation_key: relation_key, **opt
+      end
+
+      # declarations from current class and from all parents, if such present
+      def merged_plans_declarations
+        return @merged_plans_declarations if defined?(@merged_plans_declarations)
+        @merged_plans_declarations = plans_declarations || {}
+
+        sc = self
+        while (sc = sc.superclass).respond_to?(:plans_declarations)
+          @merged_plans_declarations.merge!(sc.plans_declarations)
+        end
+        @merged_plans_declarations
+      end
+
+      private
+
+      # declaration only for current class
+      def plans_declarations
+        @plans_declarations
+      end
+
+      def add_to_plans_declaration relation_key:, **opt
+        @plans_declarations ||= {}
+        opt[:dst_key] = :id unless opt.has_key?(:dst_key)
+        opt[:src_key] = :"#{relation_key}_id" unless opt.has_key?(:src_key)
+
+        @plans_declarations[relation_key] = opt
+      end
+
+    end
+
+  end
+end

data/lib/capsula/encapsulator.rb

@@ -0,0 +1,166 @@
+module Capsula
+  class Encapsulator
+
+    ##
+    # Main encapsulator functionality
+    #
+
+    def initialize items:, declarations:, keys:
+      # wrap up not wrapped obects
+      @items = wrap_non_wrapped(items)
+      @declarations = declarations
+
+      @keys = []
+      @keys_values = {}
+
+      ##
+      # Parse all declarations by first-level plans.
+      #
+      # We get a nested plans structure:
+      # [
+      #   {fruits: [:tree, {bugs: [:locations]]},
+      #   :vegetables
+      # ]
+      # For current objects which we will encapsulate now
+      # (call it first-level objects)
+      # we need to preload only :fruits and :vegetables,
+      # But when the turn comes to encapsulate :fruits,
+      # we will transfer plans for :fruits to fruits-encapsulator,
+      # and let him deside how to encapsulate tree and bugs into fruits,
+      # and then, bugs-encapsulator shoud encapsulate locations and so on.
+      #
+      keys.each do |i|
+        if i.is_a?(Hash)
+          k, v = i.first
+          @keys << k
+          @keys_values[k] = v
+        else
+          @keys << i
+        end
+      end
+
+      # for preloaded objects
+      @collections = {}
+    end
+
+    def preload_and_encapsulate
+      if (@keys - @declarations.keys).any?
+        raise StandardError.new("unknown relation keys: #{ (@keys - @declarations.keys) }")
+      end
+
+      preload
+
+      encapsulate
+
+      @items
+    end
+
+    def preload
+      @keys.each do |key|
+        dec = @declarations[key]
+        opt = build_encapsulator_options(key)
+
+        if dec.has_key?(:delegate_to)
+          # Delegate to user's encapsulator
+          preload_by_delegator(dec[:delegate_to], key, opt)
+        else
+          # Use native encapsulator
+          native_preload(key, dec, opt)
+        end
+      end
+    end
+
+    def encapsulate
+      @collections.each do |plan_key, accessories|
+        if accessories.has_key?(:delegator)
+          # Delegate to user's encapsulator
+          encapsulate_by_delegator(
+            accessories[:delegator],
+            plan_key
+          )
+        else
+          # Use native encapsulator
+          native_encapsulation(
+            plan_key,
+            accessories[:collection],
+            accessories[:declaration]
+          )
+        end
+      end
+    end
+
+    private
+
+    def preload_by_delegator delegator, key, opt
+      d = delegator.new(items: @items, opt: opt)
+      d.collect_ids_and_load_relations
+      @collections[key] = { delegator: d }
+    end
+
+    def native_preload key, dec, opt
+      # collect relation ids
+      ids = @items.map do |o|
+        get_key(o, dec[:src_key])
+      end.flatten.uniq.compact
+
+      # preload relations
+      @collections[key] = {
+        collection: (ids.any? ? dec[:dst_loader].call(ids,opt) : []),
+        declaration: dec
+      }
+    end
+
+    def encapsulate_by_delegator delegator, plan_key
+      @items.each do |i|
+        val = delegator.get_preloads_for_object(i)
+        i[plan_key] = val
+      end
+    end
+
+    def native_encapsulation plan_key, preloaded_collection, declaration
+      col = preloaded_collection
+      dec = declaration
+
+      @items.each do |i|
+        src_id = get_key(i, dec[:src_key])
+
+        val = if src_id.is_a?(Array)
+          # if object has many links to related objects (Array)
+          col.select{|c| src_id.include?(c.id) }
+        else
+          # only one link
+          col.find{|c| get_key(c, dec[:dst_key]) == src_id }
+        end
+        i[plan_key] = val
+      end
+    end
+
+    def get_key _object_, key_or_lambda
+      case key_or_lambda
+      when Symbol, String
+        _object_.send(key_or_lambda)
+      when Proc
+        key_or_lambda.call(_object_)
+      else
+        nil
+      end
+    end
+
+    def build_encapsulator_options key
+      {
+        plans: @keys_values[key] || []
+      }
+    end
+
+    def wrap_non_wrapped items
+      items.map do |item|
+        if item.class == Wrapper
+          item
+        else
+          Wrapper.new(item)
+        end
+      end
+    end
+
+  end
+end

data/lib/capsula/wrapper.rb

@@ -0,0 +1,57 @@
+module Capsula
+  class Wrapper
+
+    ##
+    # Objects-wrapper which is giving to objects ability to encapsulate other objects
+    #
+
+    attr_reader :store
+    attr_accessor :item
+
+    def initialize _object_
+      @item = _object_
+      @store = {}
+    end
+
+    # w=Capsula::Wrapper.new(1)
+    # => 1
+    # w[:a] = 2
+    # => 2
+    # w
+    # => 1
+    # w.a
+    # => 2
+    def []= key, val
+      @store[key] = val
+    end
+
+    def inspect
+      @item.inspect
+    end
+
+    def respond_to? name, is_lookup_private = false
+      self.store.include?(name) || @item.respond_to?(name, is_lookup_private)
+    end
+
+    # TODO:
+    # at first - call for wrapper, then for item (if working with hash)
+    # []
+    # fetch
+    # is_a?
+
+    if Object.respond_to?(:try)
+      def try *a, &b
+        @item.try(*a, &b)
+      end
+    end
+
+    def method_missing(method, *args, &block)
+      if store.has_key?(method)
+        store[method]
+      else
+        @item.send(method, *args, &block)
+      end
+    end
+
+  end
+end

data/spec/capsula_spec.rb

@@ -0,0 +1,90 @@
+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
+    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')
+      expect(plans).to have_key(:b)
+    end
+
+    it 'preloads objects collection' do
+      klass.plan_for(
+        :b,
+        src_key: :b_id,
+        dst_key: :id,
+        dst_loader: ->(ids,opt){ ids.map{ |i| b.new(i) } }
+      )
+      objects = [1,2].map{ |i| a.new(i) }
+      objects = klass.new(objects).plans(:b).encapsulate
+
+      puts objects.first.b
+
+      expect(objects.first).to respond_to(:b)
+      expect(objects.first).to be_a(Capsula::Wrapper)
+      expect(objects.first.b.id).to be == objects.first.b_id
+    end
+
+    it 'use lambdas in place of symbols for key-declaration' do
+      klass.plan_for(
+        :b,
+        src_key: ->(o){ o.b_id },
+        dst_key: ->(o){ o.id },
+        dst_loader: ->(ids,opt){ ids.map{ |i| b.new(i) } }
+      )
+
+      objects = [1,2].map{ |i| a.new(i) }
+      objects = klass.new(objects).plans(:b).encapsulate
+
+      expect(objects.first).to respond_to(:b)
+      expect(objects.first).to be_a(Capsula::Wrapper)
+      expect(objects.first.b.id).to be == objects.first.b_id
+    end
+
+    it 'use default keys-declaration' do
+      klass.plan_for(
+        :b,
+        dst_loader: ->(ids,opt){ ids.map{ |i| b.new(i) } }
+      )
+
+      objects = [1,2].map{ |i| a.new(i) }
+      objects = klass.new(objects).plans(:b).encapsulate
+
+      expect(objects.first).to respond_to(:b)
+      expect(objects.first).to be_a(Capsula::Wrapper)
+      expect(objects.first.b.id).to be == objects.first.b_id
+    end
+
+    it 'use custom loader' do
+      custom_loader = Class.new do
+        def initialize items:, opt: {}
+          @items = items; @opt = opt; @store = []; @b = Struct.new(:id)
+        end
+
+        def collect_ids_and_load_relations
+          ids = @items.map{ |i| i.b_id }
+          @store = ids.map{ |id| @b.new(id) }
+        end
+
+        def get_preloads_for_object o
+          @store.find { |a| o.b_id == a.id }
+        end
+      end
+
+      klass.plan_for(:b, delegate_to: custom_loader)
+
+      objects = [1,2].map{ |i| a.new(i) }
+      objects = klass.new(objects).plans(:b).encapsulate
+
+      expect(objects.first).to respond_to(:b)
+      expect(objects.first).to be_a(Capsula::Wrapper)
+      expect(objects.first.b.id).to be == objects.first.b_id
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: capsula
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Rodion V
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-02-04 00:00:00.000000000 Z
+dependencies: []
+description: The tool for encapsulating (preloading, including) related objects
+email: rodion.v@devaer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE
+- README.md
+- capsula.gemspec
+- lib/capsula.rb
+- lib/capsula/base.rb
+- lib/capsula/encapsulator.rb
+- lib/capsula/wrapper.rb
+- spec/capsula_spec.rb
+homepage: https://github.com/brlo/capsula
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.2
+signing_key: 
+specification_version: 4
+summary: Encapsulating tool
+test_files:
+- spec/capsula_spec.rb