volt-watch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 45e935cd6077ac6fca7fdefbbbf36b804c390bdd
+  data.tar.gz: 4ca467078e0bd0a7856996c417e3d5cf9b1a985d
+SHA512:
+  metadata.gz: 7861d44ac8a441fa9656a9a3beb54a70c905a6deeb0b80ce207b890a87faebbbf3d90e3341c6b0ed5baaea4e51d3627efd85b544ef83527741ab9f31932f80a3
+  data.tar.gz: f99472029b43585b43d21144c06746012547be0fe582068810ca501ccbc0ebea7f62c33d4fb2a34d0286c22fd3d99f4912322649b61dcc1321f26ce07a08fb11

data/.gitignore

@@ -0,0 +1,19 @@
+tasks
+.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/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in volt-watch.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 balmoral
+
+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,101 @@
+# Volt::Watch
+
+Volt::Watch is a helper mixin to provide simpler syntax and easy management of computation watches in Volt models and controllers.
+
+Watches can can be created for attributes, elements and values of instances of Volt::Model, Volt::ArrayModel, Volt::ReactiveArray and Volt::ReactiveHash.
+
+It further provides for creating watches on the 'internal contents' of any model, array or hash - that is, 
+to watch (and react to changes in) any object reachable from a 'root' model, array or hash. 
+  
+It keeps track of all watches created and provides a method to stop and destroy all watches.
+  
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'volt-watch'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install volt-watch
+
+## Usage
+
+Include Volt::Watch in your Volt::Model or Volt::Controller.
+
+Then in {action}_ready create the watches.
+
+Examples:
+ 
+1) to watch for a change in a specific attribute of a model,
+```
+require 'volt-watch'
+...
+module MyApp
+  class MainController < Volt::ModelController
+    include Volt::Watch
+    ...
+    def index_ready
+      watch do
+        alert "User has changed name to '#{user.name}'}
+      end
+    end
+    ...
+  end
+end
+```
+
+2) to update a view list whenever an item in array of items in store changes:
+
+```
+  def index_ready
+    on_change_in ->{ store.items } do |index|
+      update_list_item(store.items[index], index)
+    end
+    ...
+  end
+```
+
+3) to update a chart view component when any attribute in a chart model, or any nested attribute (to any level) changes:
+
+```
+  def index_ready
+    on_deep_change_in ->{ page._chart } do |model, locus, value|
+      # `model` may be page._chart or any of its attributes or their attributes
+      # which are models or arrays.
+      # `locus` identifies where the change in the model or array has occurred
+      # as a symbol (for a model attribute) or integer (for an array element's index).
+      # `value` is the new value.
+      # If an array has changed size then `model` will be the array, 
+      # `locus` will be `:size` and `value` will be the new size.
+      update_chart_view(model, locus, value)
+    end
+    ...
+  end
+```
+
+**IMPORTANT**
+
+Watches should be terminated when no longer required, such as when the page is left.
+
+To terminate all watches call `stop_watches`. 
+
+For example:
+
+```
+def before_index_remove
+  stop_watches
+end
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/[my-github-username]/volt-watch/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

data/Rakefile

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

data/lib/volt/watch/version.rb

@@ -0,0 +1,5 @@
+module Volt
+  module Watch
+    VERSION = "0.1.0"
+  end
+end

data/lib/volt/watch.rb

@@ -0,0 +1,328 @@
+module Volt
+  module Watch
+
+    # Add reactivity to the given proc.
+    #
+    # The proc will be called if any reactive
+    # attribute accessed in the proc changes.
+    #
+    # For example:
+    #
+    # ```
+    #   watch do
+    #     puts person._name
+    #   end
+    # ```
+    #
+    # The behaviour is identical to doing
+    #
+    # ```
+    #   ->{ puts person._name }.watch!
+    # ```
+    #
+    # Alias is :watch
+    def watch(proc = nil, &block)
+      add_watch(proc || block)
+    end
+    alias_method :activate, :watch
+
+
+    # Adds a watch for a shallow change in the contents
+    # (attributes, elements, or key-value pairs) of a
+    # Volt::Model, Volt::ArrayModel, Volt::ReactiveArray)
+    # or Volt::ReactiveHash.
+    #
+    # When any value in the model, array or hash changes then
+    # the given block will be called.
+    #
+    # The values of a Volt::Model are its attributes.
+    #
+    # The values of an Volt::ArrayModel are its elements.
+    #
+    # The values of an Volt::ReactiveHash are its key-value pairs.
+    #
+    # The attribute_name/index/key of the changed value will be
+    # passed as the first argument to the given block. The new
+    # associated value will be passed as the second argument.
+    #
+    # For example:
+    #
+    # ```
+    #   on_change_in ->{ user } do |attr, value|
+    #     puts "user.#{attr} => #{value}"
+    #   end
+    # ```
+    # or
+    #
+    # ```
+    #   on_change_in ->{ user } do |attr|
+    #     puts "user.#{attr} => #{user.get(attr)}"
+    #   end
+    # ```
+    # or
+    #
+    # ```
+    #   on_change_in ->{ page._items} do |index, value|
+    #     puts "page[#{index}] => #{item}"
+    #   end
+    # ```
+    # or
+    #
+    # ```
+    #   on_change_in ->{ page._items} do |index|
+    #     puts "page[#{index}] => #{page._items[index]}"
+    #   end
+    # ```
+    # or
+    #
+    # ```
+    #   on_change_in ->{ store.dictionary } do |key, entry|
+    #     puts "dictionary[#{key}] => #{entry}"
+    #   end
+    # ```
+    # or
+    # ```
+    #   on_change_in ->{ store.dictionary } do |key|
+    #     puts "dictionary[#{key}] => #{store.dictionary[key]}"
+    #   end
+    # ```
+    def on_change_in(*args, except: nil, &block)
+      args.each do |arg|
+        ensure_reactive(arg)
+        traverse(arg, :shallow, except, block)
+      end
+    end
+
+    # Does a deep traversal of all values reachable from
+    # the given root object(s).
+    #
+    # Such values include:
+    #   * attributes and field values of Volt::Model's
+    #   * size and elements of Volt::ArrayModel's
+    #   * size and elements of Volt::ReactiveArray's
+    #   * size and key-value pairs of Volt::ReactiveHash's
+    #   * nested values of the above
+    #
+    # The root(s) may be a Volt::Model, Volt::ArrayModel,
+    # Volt::ReactiveArray or Volt::ReactiveHash.
+    #
+    # If the given block accepts zero or one argument then
+    # the block will be called with the root object as the argument
+    # whenever any change occurs at any depth. This mode is
+    # suitable when watching for deep changes to the contents
+    # of a model/array/hash but you DO NOT need to identify
+    # the particular value that changed.
+    #
+    # If the given block accepts two or more arguments then
+    # the block will be called when any value reachable from
+    # (one of) the root(s) changes and will be passed three arguments:
+    #   1. the parent (owner) of the value that changed
+    #      i.e. the model, array or hash holding the value
+    #   2. the locus of the value, either:
+    #      * the attribute or field name for a model
+    #      * the index in an array
+    #      * the key in a hash
+    #      * the symbol :size if array or hash size changes
+    #   3. the new value
+    # The block may choose to accept 2 or 3 arguments.
+    # This mode is suitable when watching for deep changes
+    # to the contents of a model/array/hash and you DO need
+    # to identify what value that changed.
+    #
+    # In both modes, an optional argument specifying attributes
+    # you don't want to watch may be given with the :except
+    # keyword argument. The argument should be a symbol or
+    # integer or array of symbols or integers matching model
+    # attributes, array indexes or hash keys which you wish
+    # to ignore changes to. It may also include `:size` if you
+    # wish to ignore changes to the size of arrays or hashes.
+    # TODO: make :except more precise, perhaps with pairs of
+    # [parent, locus] to identify exceptions more accurately.
+    # Also allow for [Class, locus] to except any object of
+    # the given class.
+    #
+    # For example:
+    #
+    # ```
+    #   class Contact < Volt::Model
+    #     field :street
+    #     field :city
+    #     field :zip
+    #     field :country
+    #     field :phone
+    #     field :email
+    #   end
+    #
+    #   class Customer < Volt::Model
+    #     field :name
+    #     field :contact
+    #   end
+    #
+    #   class Order < Volt::Model
+    #     field :customer
+    #     field :product
+    #     field :date
+    #     field :quantity
+    #   end
+    #
+    #   ...
+    #
+    #   def shallow_order_watch
+    #     # one argument in given block has no detail of change
+    #     on_deep_change_in orders do |store._orders|
+    #       puts "something unknown changed in orders"
+    #     end
+    #   end
+    #
+    #   def on_deep_change_in
+    #     # three arguments in given block gives detail of change
+    #     on_deep_change_in store._orders do |context, locus, value|
+    #       case
+    #         when context == store._orders
+    #           if locus == :size
+    #             puts "orders.size has changed to #{value}"
+    #           else
+    #             index = locus
+    #             puts "orders[#{index}] has changed to #{value}"
+    #           end
+    #         when context.is_a? Order
+    #           order, attr = context, locus
+    #           puts "Order[#{order.id}].#{attr} has changed to #{value}"
+    #         when context.is_a? Customer
+    #           customer, attr = context, locus
+    #           puts "customer #{customer.id} #{attr} has changed to #{value}"
+    #       end
+    #     end
+    #   end
+    # ```
+    #
+    def on_deep_change_in(*roots, except: nil, &block)
+      roots.each do |root|
+        ensure_reactive(root)
+        if block.arity <= 1
+          add_watch( ->{ traverse(root, :root, except, block) } )
+        else
+          traverse(root, :node, except, block)
+        end
+      end
+    end
+
+    # Stops and destroys all current watches.
+    # Call when watches are no longer required.
+    # Should typically be called when leaving a page,
+    # for example in `before_{action}_remove`
+    def stop_watches
+      if @watches
+        @watches.each do |b|
+          b.stop
+        end
+        @watches = nil
+      end
+    end
+
+    private
+
+    def ensure_reactive(model)
+      unless reactive?(model)
+        raise ArgumentError, 'argument must be Volt Model, ArrayModel, ReactiveArray or ReactiveHash'
+      end
+    end
+
+    def reactive?(model)
+      Volt::Model === model ||
+      Volt::ArrayModel === model ||
+      Volt::ReactiveArray == model ||
+      Volt::ReactiveHash === model
+    end
+
+    def traverse(node, mode, except, block)
+      if node.is_a?(Volt::Model)
+        traverse_model(node, mode, except, block)
+      elsif node.is_a?(Volt::ReactiveArray)
+        traverse_array(node, mode, except, block)
+      elsif node.is_a?(Volt::ReactiveHash)
+        traverse_hash(node, mode, except, block)
+      end
+    end
+
+    def traverse_array(array, mode, except, block)
+      compute_size(hash, mode, except, block)
+      array.size.times do |i|
+        # must access through array[i] to trigger dependency
+        compute_value(array, i, ->{ array[i] }, mode, except, block)
+      end
+      unless mode == :shallow 
+        array.size.times do |i|
+          traverse(array[i], mode, except, block)
+        end
+      end
+    end
+
+    def traverse_hash(hash, mode, except, block)
+      compute_size(hash, mode, except, block)
+      hash.each_key do |key|
+        # must access through hash[key] to trigger dependency
+        compute_value(hash, key, ->{ hash[key] }, mode, except, block)
+      end
+      unless mode == :shallow
+        hash.each_value do |value|
+          traverse(value, mode, except, block)
+        end
+      end
+    end
+
+    def traverse_model(model, mode, except, block)
+      traverse_model_attrs(model, mode, except, block)
+      traverse_model_fields(model, mode, except, block)
+    end
+
+    def traverse_model_attrs(model, mode, except, block)
+      model.attributes.each_key do |attr|
+        # must access through get(attr) to trigger dependency
+        compute_value(model, attr, ->{ model.get(attr) }, mode, except, block)
+      end
+      unless mode == :shallow
+        model.attributes.each_key do |attr|
+          traverse(model.get(:"#{attr}"), mode, except, block)
+        end
+      end
+    end
+
+    def traverse_model_fields(model, mode, except, block)
+      fields = model.class.fields_data
+      if fields
+        fields.each_key do |attr|
+          # must access through send(attr) to trigger dependency
+          compute_value(model, attr, ->{ model.send(attr) }, mode, except, block)
+        end
+        unless mode == :shallow 
+          fields.each_key do |attr|
+            traverse(model.send(attr), mode, except, block)
+          end
+        end
+      end
+    end
+
+    def compute_value(parent, locus, value, mode, except, block)
+      unless except && except.include?(locus)
+        compute_term mode, ->{ block.call(parent, locus, value.call) }
+      end
+    end
+
+    def compute_size(collection, mode, except, block)
+      unless except && except.include?(:size)
+        compute_term mode, ->{ block.call(collection, :size, collection.size) }
+      end
+    end
+
+    def compute_term(mode, proc)
+      # :shallow and :node should watch, :root doesn't
+      mode == :root ? proc.call : add_watch(proc)
+    end
+
+    def add_watch(proc)
+      (@watches ||= []) << proc.watch!
+    end
+
+  end
+end

data/lib/volt-watch.rb

@@ -0,0 +1 @@
+require 'volt/watch'

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+# Volt sets up rspec and capybara for testing.
+require 'volt/spec/setup'
+Volt.spec_setup
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

data/spec/volt/watch_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Volt::Watch do
+  it 'should have a version number' do
+    expect(Volt::Watch::VERSION).not_to be nil
+  end
+
+  it 'should do something useful' do
+    expect(false).to be true
+  end
+end

data/volt-watch.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'volt/watch/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'volt-watch'
+  spec.version       = Volt::Watch::VERSION
+  spec.authors       = ['Colin Gunn']
+  spec.email         = ['colgunn@icloud.com']
+  spec.summary       = %q{Helper plugin for to provide easy reactivity bindings in Volt models and controllers.}
+  spec.homepage      = 'https://github.com/balmoral/volt-watch'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'volt', '~> 0.9.5.0'
+  spec.add_development_dependency 'rspec', '~> 3.2.0'
+  spec.add_development_dependency 'rake'
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: volt-watch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Colin Gunn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: volt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.5.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- colgunn@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/volt-watch.rb
+- lib/volt/watch.rb
+- lib/volt/watch/version.rb
+- spec/spec_helper.rb
+- spec/volt/watch_spec.rb
+- volt-watch.gemspec
+homepage: https://github.com/balmoral/volt-watch
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Helper plugin for to provide easy reactivity bindings in Volt models and
+  controllers.
+test_files:
+- spec/spec_helper.rb
+- spec/volt/watch_spec.rb
+has_rdoc: