volt-repo_cache 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9cb06385cea5ffc9a2c6518ec011d99c65957550
+  data.tar.gz: b88fab46ec514ac59bf7da97a84e2c3461fee23b
+SHA512:
+  metadata.gz: ff6af4ea44e4067961a8a3fd289004736538ab165cec33c8a258ae7c5cb770cc120f9d4267adb179a1843ccd6b26df349d0b4683a51bfb324bb22f3a3199b641
+  data.tar.gz: e0616aded5eaff2f4079a7a28e645baf48004e12d5eaeb8119c7086b5266f7cd3ac32d76b4c0d1ea053e0889215be45ed8e73359ad35fb56922aad12aa9ae6b3

data/.gitignore

@@ -0,0 +1,19 @@
+make
+.idea
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in volt-repo_cache.gemspec
+gemspec
+
+# Optional Gems for testing/dev
+
+# The implementation of ReadWriteLock in Volt uses concurrent ruby and ext helps performance.
+gem 'concurrent-ruby-ext', '~> 0.8.0'
+
+# Gems you use for development should be added to the gemspec file as
+# development dependencies.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Colin Gunn
+
+MIT License
+
+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,314 @@
+# Volt::RepoCache
+
+- Provides client-side caching of repository (db) collections, models and their associations.
+- Loads multiple associated collections (or query based subsets) into a cache.
+- Buffers changes to models, collections and associations until flushed.
+- Allows for flushes to be performed at model, collection or cache level.
+- Provides increased associational integrity.
+- Reduces the burden of promise handling in repository (db) operations.
+- Is ideal for use where multiple associated models are being displayed and edited.
+- Preserves standard Volt model and collection interfaces and reactivity.
+ 
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'volt-repo_cache'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install volt-repo_cache
+
+## Usage
+
+Assume we have a sales application with three model classes:
+
+    class Customer < Volt::Model
+      field :name
+      has_many :orders
+    end
+        
+    class Product < Volt::Model
+      field :name
+      field :price
+      has_many :orders
+    end
+        
+    class Order < Volt:Model
+      belongs_to :customer
+      belongs_to :product
+      field :date
+      field :quantity
+    end
+
+Let's say we want to cache all customers, products,
+and orders, the latter between some given dates.
+
+The following code will create the cache and load it
+in a controller's `index` method. We'll also add a 
+`before_index_remove` method to clear the cache
+when leaving the page.
+
+#### Example 1 - defining and loading a cache
+
+    class OrderController < Volt::ModelController
+
+      def index
+        new_cache.loaded.then do |cache|
+          page._cache = cache
+        end.fail do |errors|
+          flashes << errors.to_s
+        end
+      end
+      
+      def new_cache
+        Volt::RepoCache.new(
+          Volt.current_app.store,
+          customer: { 
+            has_many: :orders,
+          }
+          product:  {
+            has_many: :orders, 
+          }
+          order: { 
+            belongs_to: [:customer, :product] 
+            where: {'$and' => [:date => {'$gte' => start_date}, :date => {'$lte' => end_date}]} 
+          }
+        )
+      end
+    
+      def before_index_remove
+        page._cache.clear if _cache
+      end
+    
+      ...
+    end
+
+**Under Volt 0.9.7 the specification of associations
+will be provided by the underlying models' class
+definitions and will no longer be required in 
+the cache options.**
+
+In the `index` method we only need to resolve
+one promise when the cache is `loaded`. 
+
+Collections may be identified in the singular or plural
+according to preference, e.g. `order:` or `orders:`,
+with or without an underscore prefix.
+
+A `where:` or `query:` option may be provided for each collection
+to specify which models are loaded from the repository.
+The default behaviour is to load all models in a collection.
+
+Resolution of associations between cached models will
+depend on what has been loaded into the cache for
+each collection. 
+
+After the cache is loaded you can then access 
+collections, models and associations without 
+handling promise resolution or failure. 
+
+Otherwise, the interfaces to cached models and collections
+largely behave as normal.
+
+#### Example 2 - query and association resolution
+
+    # find all orders for customer 'ABC and product 'XYZ' 
+    cache._customers.where(name: 'ABC').orders.select { |order|
+      order.product.name == 'XYZ'
+    }  
+
+Unlike a standard Volt query and association call 
+(`order.product`) we have no intervening promise(s) to
+resolve, and also avoid relatively slow database request(s).
+
+#### Example 3 - query and association resolution
+
+    # total cost of products ordered by customer
+    customer = cache._customers.where(name: 'ABC')
+    total_cost = customer.orders.reduce(0) do |sum, order|
+      sum + (order.quantity * order.product.price)
+    end
+
+Again, no promises to resolve and faster calculation of
+total cost than would be the case with uncached database
+access.
+
+### Changes and flushing
+
+Changes to field values in models are buffered until
+flushed (saved) to the database. Flushes may be requested
+at the model, collection or cache level. Each flush
+returns a single promise. Some examples:
+
+#### Example 4 - change and save a single model
+
+    # change the price of a product and save it
+    product = cache._products.where(name: 'XYZ')
+    product.price = 9.99
+    # flush the product model
+    product.flush!.then do |result|
+      puts "#{result} saved"
+    end.fail do |errors|
+      puts errors
+    end
+    
+#### Example 5 - change and save several models in a collection
+
+    # change the price of multiple products
+    # and save them all together
+    products = cache._products
+    products.where(name: 'X').price = 7.77
+    products.where(name: 'Y').price = 8.88
+    products.where(name: 'Z').price = 9.99
+    # flush the 'products' collection
+    products.flush!.then do |result|
+      puts "all products saved"
+    end.fail do |errors|
+      puts "error saving products: #{errors}"
+    end
+    
+#### Example 6 - change and save models in more than one collection
+    
+    # change the price of a product
+    # and the name of a customer
+    # and save them together
+    cache._products.where(name: 'XYZ').price = 7.77
+    cache._customer.where(name: 'ABC').name = 'EFG'
+    # flush the whole cache 
+    cache.flush!.then do |result|
+      puts "cached flushed successfully"
+    end.fail do |errors|
+      puts "error flushing cache: #{errors}"
+    end
+   
+### Creating new models with no owners
+   
+There are two ways to create a new instance of a model
+not belonging to another model:
+ 
+#### Example 7 - create a new model (with no owner) via a collection
+
+    # create a new product
+    p = Product.new(name: 'IJK')
+    cache._products << p
+    
+A new model must be added to the appropriate cached collection 
+(using `#<<` or `#append`) before it also is cached. It will 
+not be saved to the database until the model or its containing
+collection or cache is flushed.
+
+NB Both `#<<` and `#append` return the collection, not the
+appended model. 
+
+Another way of creating a new model via a collection using a hash:
+ 
+#### Example 8 - create a new model (with no owner) via a collection
+
+    # create a new product
+    cache._products << {name: 'IJK'}
+    p = cache._products.where(name: 'IJK')
+        
+### Creating new models with owners
+
+When creating a new model which belongs to one or more models
+you must set the foreign key id(s) to establish the association(s).
+
+#### Example 9 - create a new model (with two owners) via a collection
+
+    # create a new order which belongs to a customer and a product
+    product = cache._products.where(code: 'XYZ')
+    customer = cache._customers.where(code: 'ABC')
+    order = Order.new(product_id: product.id, customer_id: customer.id, quantity: 1, date: Date.today)
+    cache._orders << order
+  
+An easier way is ask an owner model to create a new owned model:
+    
+#### Example 10 - create a new model (with two owners) via an owner model
+    
+    product = cache._products.where(code: 'XYZ')
+    customer = cache._customers.where(code: 'ABC')
+    # ask the customer to create a new order, give it the product id
+    order = customer.new_order(product_id: product.id, quantity: 1, date: Date.today)
+    
+### Destroying models
+ 
+Models in the cache can be marked for destruction when the cache is flushed using `#mark_for_destruction!`.
+Still to do - associational integrity checks when marking for destruction.
+   
+## Warnings
+
+**Flushes to the underlying repository are not atomic and cannot be rolled back**. 
+If part of the cache/collection/model/association 
+flush fails the transaction(s) may lose integrity.
+
+The cached models and collections contain circular references
+(the models refer to the collection which contains them and 
+collections refer to the cache). Not being sure what the 
+implications are for efficient garbage collection (in Ruby
+on the server and Javascript on the client), a method 
+is provided to clear the cache when it is no longer required,
+breaking all internal (circular) references.
+
+## TODO
+
+1. Use associations_data in Volt::Models when 0.9.7 (sql) version available.
+2. Handle non-standard collection, foreign_key and local_key Volt model options. 
+3. Association integrity checks on mark_for_destruction!
+4. Test spec.
+5. Locking?
+6. Atomic transactions?
+7. Removal of circular references?
+
+## Contributing and use
+
+This gem was written as part of the development of a production 
+application, primarily to speed up processing requiring many 
+implicit database queries (across associated collections), as well
+as simplifying association management and reducing the burden of
+asynchronous promise resolution.
+
+It works well enough for our current application's needs, 
+but it may not be suitable for all requirements.
+
+We will look at extending the cache framework to support locking and
+atomic transactions (with rollback), but in the meantime if you have
+a need or interest in this area your suggestions and contributions
+are very welcome.
+
+To contribute:
+
+1. Fork it ( http://github.com/[my-github-username]/volt-repo_cache/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 new Pull Request
+
+## License
+
+Copyright (c) 2015 Colin Gunn
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/volt/repo_cache.rb

@@ -0,0 +1,6 @@
+require 'volt/repo_cache/util'
+require 'volt/repo_cache/model_array'
+require 'volt/repo_cache/association'
+require 'volt/repo_cache/model'
+require 'volt/repo_cache/collection'
+require 'volt/repo_cache/cache'

data/lib/volt/repo_cache/association.rb

@@ -0,0 +1,100 @@
+module Volt
+  module RepoCache
+    class Association
+      include Volt::RepoCache::Util
+
+      attr_reader :local_name_singular, :local_name_plural
+      attr_reader :local_collection
+      attr_reader :foreign_name, :foreign_collection_name
+      attr_reader :foreign_model_class_name, :foreign_model_class
+      attr_reader :type, :foreign_id_field, :local_id_field
+
+      def initialize(local_collection, foreign_name, type)
+        _local_name = local_collection.name.to_s.sub(/^_/, '')
+        @local_name_singular = _local_name.singularize.to_sym
+        @local_name_plural = _local_name.pluralize.to_sym
+        @local_collection = local_collection
+        @foreign_name = foreign_name
+        @type = type
+        @foreign_model_class_name = @foreign_name.to_s.singularize.camelize
+        @foreign_model_class = Object.const_get(@foreign_model_class_name)
+        @foreign_collection_name = :"_#{@foreign_name.to_s.pluralize}"
+        @foreign_id_field = has_any? ? :"#{@local_collection.model_class_name.underscore}_id" : :id
+        @local_id_field = belongs_to? ? :"#{@foreign_name.to_s}_id" : :id
+      end
+
+      # Hide circular references to local
+      # and foreign collections for inspection.
+      def inspect
+        __local = @local_collection
+        __foreign = @foreign_collection
+        @local_collection = "{{#{@local_collection ? @local_collection.name : :nil}}"
+        @foreign_collection = "{{#{@foreign_collection ? @foreign_collection.name : :nil}}"
+        result = super
+        @local_collection = __local
+        @foreign_collection = __foreign
+        result
+      end
+
+      def cache
+        @local_collection.cache
+      end
+
+      # Must be lazy initialization since we
+      # don't know order in which collections
+      # will be loaded to cache.
+      def foreign_collection
+        @foreign_collection ||= cache.collections[@foreign_collection_name]
+      end
+
+      # Returns the reciprocal association
+      # which may be nil if the foreign_collection
+      # is not interested (has not specified)
+      # the reciprocal association.
+      # It may be, for example, that this association
+      # is a belongs_to, but there is no reciprocal
+      # has_one or has_many association in the 'owner'.
+      # Must be lazy initialization since it depends on
+      # foreign_collection being lazily initialized.
+      def reciprocal
+        unless @reciprocal
+          # debug __method__, __LINE__, ""
+          @reciprocal = foreign_collection.associations.values.detect do |a|
+            # debug __method__, __LINE__, "#{a.foreign_collection.name} ?==? #{local_collection.name}"
+            a.foreign_collection.name == local_collection.name
+          end
+          @reciprocal = :nil unless @reciprocal
+          # debug __method__, __LINE__, "reciprocal of #{self.inspect} is #{@reciprocal.inspect}"
+        end
+        @reciprocal == :nil ? nil : @reciprocal
+      end
+
+      def reciprocated?
+        !!reciprocal
+      end
+
+      def has_one?
+        type == :has_one
+      end
+
+      def has_many?
+        type == :has_many
+      end
+
+      def has_any?
+        has_one? || has_many?
+      end
+
+      def belongs_to?
+        type == :belongs_to
+      end
+
+      private
+
+      def uncache
+        @local_collection = @foreign_collection = @reciprocal = nil
+      end
+
+    end
+  end
+end