hyper-resource 1.0.0.lap34

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f56e1c745c9154f2197accee8cbd76fb6b623fcf112f11caedc29d4dcc0ee7f
+  data.tar.gz: c74e55520edf0064cb02ff378a70e55145a0400c21c65976de466ec283446a60
+SHA512:
+  metadata.gz: d2fc69f4ad34347ecae9d5eac09c00c3f023b86306b1ceaab8b9593521b74db02751bbc8cb611e842f1a8f7b02f5cff2f954db9f5f2f0755facaccdd64a220c5
+  data.tar.gz: 553518e63790f5e7bb2d8b57d24113c86a074d2d985aaf787ebb263f3b4e7409d22d136d2dada4e5a7c601a353c0588f2d5ef46854540cff3f62be786f3663d0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Jan Biedermann
+
+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,109 @@
+# hyper-resource
+
+HyperResource is an affective way of moving data between your server and clients when using Hyperloop and Rails.
+
+[![Reactivity Demo](http://img.youtube.com/vi/fPSpESBbeMQ/0.jpg)](http://www.youtube.com/watch?v=fPSpESBbeMQ "Reactivity Demo")
+
+## Motivation
+
++ To co-exist with a resource based REST API
++ To have ActiveRecord type Models shared by both the client and server code
++ To be ORM/database agnostic (tested with ActiveRecord on Postgres and Neo4j.rb on Neo4j)
++ To fit the 'Rails way' as far as possible (under the covers, HyperResource is a traditional REST API)
++ To keep all Policy checking and authorisation logic in the Rails Controllers
++ To allow a stages implementation
+
+## Staged implementation
+
+HyperResource is designed to be implemented in stages and each stage delivers value in its own right, so the developer only needs to go as far as they like.
+
+A record can be of any ORM but the ORM must implement:
+```ruby
+record_class.find(id) # to get a record
+record.id # a identifier
+record.updated_at # a time stamp
+record.destroyed? # to identify if its scheduled for destruction
+
+# when using relations controller
+record.touch # to update updated_at, identicating that something about that record changed
+             # for example it has been added to a relation
+```
+
+### Stage 1 - Wrap a REST API with Ruby classes to represent Models
+
+The simplest implementation of HyperResource is a client side only wrapper of an existing REST API which treats each REST Resource as a Ruby class.
+
+```ruby
+# in your client-cide code
+class Customer
+  include ApplicationHyperRecord
+end
+
+# then work with the Customer class as if it were an ActiveRecord
+customer = Customer.new(name: 'John Smith')
+customer.save # ---> POST api/customer.json ... {name: 'John Smith' }
+puts customer.id # 123
+
+# to find a record
+customer = Customer.find(123) # ---> GET api/customer/123.json
+puts customer.name # `John Smith`
+```
+
+### Stage 2 - Adapt your Models so the client and server code share the same Models
+
+HyperResource supports ActiveRecord associations and scopes so you can DRY up your code and the client an server can share the same Models.
+
+```ruby
+module ApplicationHyperRecord
+  def self.included(base)
+    if RUBY_ENGINE == 'opal'
+      base.include(HyperRecord)
+    else
+      base.extend(HyperRecord::ServerClassMethods)
+    end
+  end
+end
+
+class Customer
+  include ApplicationHyperRecord
+  has_many :addresses
+
+  unless RUBY_ENGINE == 'opal'
+    # methods which should only exist on the server
+  end
+end
+
+customer = Customer.find(123) # ---> GET api/customer/123.json
+customer.addresses.each do |address|
+  puts address.post_code
+end
+```
+
+### Stage 3 - Implement a Redis based pub-sub mechanism so the client code is notified when the server data changes
+
+```ruby
+class ApplicationController
+  include Hyperloop::Resource::PubSub
+
+  def my_action
+    # available methods for pubsub
+    publish_collection(base_record, collection_name, record = nil)
+    publish_record(record)
+    publish_scope(record_class, scope_name)
+
+    subscribe_collection(collection, base_record = nil, collection_name = nil)
+    subscribe_record(record)
+    subscribe_scope(collection, record_class = nil, scope_name = nil)
+
+    pub_sub_collection(collection, base_record, collection_name, causing_record = nil)
+    pub_sub_record(record)
+    pub_sub_scope(collection, record_class, scope_name)
+  end
+end
+```
+
+EXAMPLE
+
+## Implementation
+
+How to install....

data/hyper-resource.gemspec

@@ -0,0 +1,30 @@
+require_relative "lib/hyperloop/resource/version"
+
+Gem::Specification.new do |s|
+  s.name         = "hyper-resource"
+  s.version      = Hyperloop::Resource::VERSION
+  s.author       = "Jan Biedermann"
+  s.email        = "jan@kursator.de"
+  s.homepage     = "https://github.com/janbiedermann/hyper-resource"
+  s.summary      = "Transparent Opal Ruby Data/Resource Access from the browser for Ruby-Hyperloop"
+  s.description  = "Write Browser Apps that transparently access server side resources like 'MyModel.first_name', with ease"
+
+  s.files          = `git ls-files`.split("\n")
+  s.executables    = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.test_files     = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths  = ["lib"]
+
+  s.add_runtime_dependency "opal", "~> 0.11.0"
+  s.add_runtime_dependency "opal-activesupport", "~> 0.3.1"
+  s.add_runtime_dependency 'hyper-component' , '~> 1.0.0.lap27'
+  s.add_runtime_dependency 'hyper-store' , '~> 1.0.0.lap27'
+  s.add_runtime_dependency "hyperloop-config", "~> 1.0.0.lap27"
+  s.add_development_dependency "hyperloop", "~> 1.0.0.lap27"
+  s.add_development_dependency "hyper-spec", "~> 1.0.0.lap27"
+  s.add_development_dependency "listen"
+  s.add_development_dependency "rake", ">= 11.3.0"
+  s.add_development_dependency "rails", ">= 5.1.0"
+  s.add_development_dependency "redis"
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "sqlite3"
+end

data/lib/hyper-resource.rb

@@ -0,0 +1,20 @@
+require 'hyperloop-config'
+require 'opal-activesupport'
+Hyperloop.import 'pusher/source/pusher.js', client_only: true
+require 'hyperloop/resource/version'
+require 'hyperloop/resource/client_drivers' # initialize options for the client
+require 'hyperloop/resource/config'
+require 'hyper-store'
+Hyperloop.import 'hyper-resource'
+
+
+if RUBY_ENGINE == 'opal'
+  require 'hyperloop/resource/http'
+  require 'hyper-store'
+  require 'hyper_record'
+else
+  require 'hyperloop/resource/pub_sub' # server side, controller helper methods
+  require 'hyperloop/resource/security_guards' # server side, controller helper methods
+  require 'hyper_record'
+  Opal.append_path __dir__.untaint
+end

data/lib/hyper_record.rb

@@ -0,0 +1,21 @@
+if RUBY_ENGINE == 'opal'
+  require 'hyper_record/dummy_value'
+  require 'hyper_record/collection'
+  require 'hyper_record/class_methods'
+  require 'hyper_record/client_instance_methods'
+
+  module HyperRecord
+    def self.included(base)
+      base.include(Hyperloop::Store::Mixin)
+      base.extend(HyperRecord::ClassMethods)
+      base.include(HyperRecord::ClientInstanceMethods)
+      base.class_eval do
+        state :record_state
+      end
+    end
+  end
+else
+  require 'hyper_record/server_class_methods'
+end
+
+

data/lib/hyper_record/class_methods.rb

@@ -0,0 +1,413 @@
+module HyperRecord
+  module ClassMethods
+
+    def new(record_hash = {})
+      if record_hash.has_key?(:id)
+        record = _record_cache[record_hash[:id]]
+        if record
+          record.instance_variable_get(:@properties_hash).merge!(record_hash)
+          return record
+        end
+      end
+      super(record_hash)
+    end
+
+    def all
+      _register_class_observer
+      if _class_fetch_states[:all] == 'f'
+        record_collection = HyperRecord::Collection.new
+        _record_cache.each_value { |record| record_collection.push(record) }
+        return record_collection
+      end
+      _promise_get("#{resource_base_uri}.json").then do |response|
+        klass_name = self.to_s.underscore
+        klass_key = klass_name.pluralize
+        response.json[klass_key].each do |record_json|
+          self.new(record_json[klass_name])
+        end
+        _class_fetch_states[:all] = 'f'
+        _notify_class_observers
+        record_collection = HyperRecord::Collection.new
+        _record_cache.each_value { |record| record_collection.push(record) }
+        record_collection
+      end.fail do |response|
+        error_message = "#{self.to_s}.all failed to fetch records!"
+        `console.error(error_message)`
+        response
+      end
+      HyperRecord::Collection.new
+    end
+
+    def belongs_to(direction, name = nil, options = { type: nil })
+      if name.is_a?(Hash)
+        options.merge(name)
+        name = direction
+        direction = nil
+      elsif name.nil?
+        name = direction
+      end
+      reflections[name] = { direction: direction, type: options[:type], kind: :belongs_to }
+      define_method(name) do
+        _register_observer
+        if @fetch_states[name] == 'f'
+          @relations[name]
+        elsif self.id
+          self.class._promise_get("#{self.class.resource_base_uri}/#{self.id}/relations/#{name}.json").then do |response|
+            @relations[name] = self.class._convert_json_hash_to_record(response.json[self.class.to_s.underscore][name])
+            @fetch_states[name] = 'f'
+            _notify_observers
+            @relations[name]
+          end.fail do |response|
+            error_message = "#{self.class.to_s}[#{self.id}].#{name}, a has_one association, failed to fetch records!"
+            `console.error(error_message)`
+            response
+          end
+          @relations[name]
+        else
+          @relations[name]
+        end
+      end
+      define_method("#{name}=") do |arg|
+        _register_observer
+        @relations[name] = arg
+        @fetch_states[name] == 'f'
+        @relations[name]
+      end
+    end
+
+    def create(record_hash = {})
+      record = new(record_hash)
+      record.save
+      record
+    end
+
+    def find(id)
+      return _record_cache[id] if _record_cache.has_key?(id)
+
+      observer = React::State.current_observer
+      record_in_progress = self.new
+
+      record_in_progress_key = "#{self.to_s}_#{record_in_progress.object_id}"
+      React::State.get_state(observer, record_in_progress_key) if observer
+
+      _promise_get("#{resource_base_uri}/#{id}.json").then do |response|
+        klass_key = self.to_s.underscore
+        reflections.keys.each do |relation|
+          if response.json[klass_key].has_key?(relation)
+            response.json[klass_key][r_or_s] = _convert_array_to_collection(response.json[klass_key][relation])
+            record_in_progress.instance_variable_get(:@fetch_states)[relation] = 'f'
+          end
+        end
+        record_in_progress._initialize_from_hash(response.json[klass_key]) if response.json[klass_key]
+        _record_cache[record_in_progress.id] = record_in_progress
+        React::State.set_state(observer, record_in_progress_key, `Date.now() + Math.random()`) if observer
+        record_in_progress
+      end.fail do |response|
+        error_message = "#{self.to_s}.find(#{id}) failed to fetch record!"
+        `console.error(error_message)`
+        response
+      end
+
+      record_in_progress
+    end
+
+    def find_record(id)
+      # TODO this is bogus, needs some attention
+      _promise_get("#{resource_base_uri}/#{id}.json").then do |response|
+        klass_name = self.to_s.underscore
+        self.new(response.json[klass_name])
+      end
+    end
+
+    def find_record_by(hash)
+      return _record_cache[hash] if _record_cache.has_key?(hash)
+      # TODO needs clarification about how to call the endpoint
+      _promise_get("#{resource_base_uri}/#{id}.json").then do |reponse|
+        record = self.new(response.json[self.to_s.underscore])
+        _record_cache[hash] = record
+      end
+    end
+
+    def has_many(direction, name = nil, options = { type: nil })
+      if name.is_a?(Hash)
+        options.merge(name)
+        name = direction
+        direction = nil
+      elsif name.nil?
+        name = direction
+      end
+      reflections[name] = { direction: direction, type: options[:type], kind: :has_many }
+      define_method(name) do
+        _register_observer
+        if @fetch_states[name] == 'f'
+          @relations[name]
+        elsif self.id
+          self.class._promise_get("#{self.class.resource_base_uri}/#{self.id}/relations/#{name}.json").then do |response|
+            collection = self.class._convert_array_to_collection(response.json[self.class.to_s.underscore][name], self, name)
+            @relations[name] = collection
+            @fetch_states[name] = 'f'
+            _notify_observers
+            @relations[name]
+          end.fail do |response|
+            error_message = "#{self.class.to_s}[#{self.id}].#{name}, a has_many association, failed to fetch records!"
+            `console.error(error_message)`
+            response
+          end
+          @relations[name]
+        else
+          @relations[name]
+        end
+      end
+      define_method("#{name}=") do |arg|
+        _register_observer
+        collection = if arg.is_a?(Array)
+          HyperRecord::Collection.new(arg, self, name)
+        elsif arg.is_a?(HyperRecord::Collection)
+          arg
+        else
+          raise "Argument must be a HyperRecord::Collection or a Array"
+        end
+        @relations[name] = collection
+        @fetch_states[name] == 'f'
+        @relations[name]
+      end
+    end
+
+    def has_one(direction, name, options = { type: nil })
+      if name.is_a?(Hash)
+        options.merge(name)
+        name = direction
+        direction = nil
+      elsif name.nil?
+        name = direction
+      end
+      reflections[name] = { direction: direction, type: options[:type], kind: :has_one }
+      define_method(name) do
+        _register_observer
+        if @fetch_states[name] == 'f'
+          @relations[name]
+        elsif self.id
+          self.class._promise_get("#{self.class.resource_base_uri}/#{self.id}/relations/#{name}.json").then do |response|
+            @relations[name] = self.class._convert_json_hash_to_record(response.json[self.class.to_s.underscore][name])
+            @fetch_states[name] = 'f'
+            _notify_observers
+            @relations[name]
+          end.fail do |response|
+            error_message = "#{self.class.to_s}[#{self.id}].#{name}, a has_one association, failed to fetch records!"
+            `console.error(error_message)`
+            response
+          end
+          @relations[name]
+        else
+          @relations[name]
+        end
+      end
+      define_method("#{name}=") do |arg|
+        _register_observer
+        @relations[name] = arg
+        @fetch_states[name] == 'f'
+        @relations[name]
+      end
+    end
+
+    def record_cached?(id)
+      _record_cache.has_key?(id)
+    end
+
+    def property(name, options = {})
+      # ToDo options maybe, ddefault value? type check?
+      _property_options[name] = options
+      define_method(name) do
+        _register_observer
+        if @properties_hash[:id]
+          if @changed_properties_hash.has_key?(name)
+            @changed_properties_hash[name]
+          else
+            @properties_hash[name]
+          end
+        else
+          # record has not been fetched or is new and not yet saved
+          if @properties_hash[name].nil?
+            # TODO move default to initializer?
+            if self.class._property_options[name].has_key?(:default)
+              self.class._property_options[name][:default]
+            elsif self.class._property_options[name].has_key?(:type)
+              HyperRecord::DummyValue.new(self.class._property_options[name][:type])
+            else
+              HyperRecord::DummyValue.new(Nil)
+            end
+          else
+            @properties_hash[name]
+          end
+        end
+      end
+      define_method("#{name}=") do |value|
+        _register_observer
+        @changed_properties_hash[name] = value
+      end
+    end
+
+    def reflections
+      @reflections ||= {}
+    end
+
+    def rest_method(name, options = { default_result: '...' })
+      rest_methods[name] = options
+      define_method(name) do |*args|
+        _register_observer
+        if self.id && (@rest_methods_hash[name][:force] || !@rest_methods_hash[name].has_key?(:result))
+          self.class._rest_method_get_or_patch(name, self.id, *args).then do |result|
+            @rest_methods_hash[name][:result] = result # result is parsed json
+            _notify_observers
+            @rest_methods_hash[name][:result]
+          end.fail do |response|
+            error_message = "#{self.class.to_s}[#{self.id}].#{name}, a rest_method, failed to fetch records!"
+            `console.error(error_message)`
+            response
+          end
+        end
+        if @rest_methods_hash[name].has_key?(:result)
+          @rest_methods_hash[name][:result]
+        else
+          self.class.rest_methods[name][:default_result]
+        end
+      end
+    end
+
+    def rest_methods
+      @rest_methods_hash ||= {}
+    end
+
+    def resource_base_uri
+      @resource ||= "#{Hyperloop::Resource::ClientDrivers.opts[:resource_api_base_path]}/#{self.to_s.underscore.pluralize}"
+    end
+
+    def scope(name, options)
+      scopes[name] = HyperRecord::Collection.new
+      define_singleton_method(name) do
+        if _class_fetch_states[name] == 'f'
+          scopes[name]
+        else
+          _register_class_observer
+          self._promise_get("#{resource_base_uri}/scopes/#{name}.json").then do |response|
+            scopes[name] = _convert_array_to_collection(response.json[self.to_s.underscore][name])
+            _class_fetch_states[name] = 'f'
+            _notify_class_observers
+            scopes[name]
+          end.fail do |response|
+            error_message = "#{self.class.to_s}.#{name}, a scope, failed to fetch records!"
+            `console.error(error_message)`
+            response
+          end
+          scopes[name]
+        end
+      end
+    end
+
+    def scopes
+      @scopes ||= {}
+    end
+
+    ### internal
+
+    def _convert_array_to_collection(array, record = nil, relation_name = nil)
+      res = array.map do |record_hash|
+        _convert_json_hash_to_record(record_hash)
+      end
+      HyperRecord::Collection.new(res, record, relation_name)
+    end
+
+    def _convert_json_hash_to_record(record_hash)
+      return nil if !record_hash
+      klass_key = record_hash.keys.first
+      return nil if klass_key == "nil_class"
+      return nil if !record_hash[klass_key]
+      return nil if record_hash[klass_key].keys.size == 0
+      record_class = klass_key.camelize.constantize
+      if record_hash[klass_key][:id].nil?
+        record_class.new(record_hash[klass_key])
+      else
+        record = record_class._record_cache[record_hash[klass_key][:id]]
+        if record.nil?
+          record = record_class.new(record_hash[klass_key])
+        else
+          record._initialize_from_hash(record_hash[klass_key])
+        end
+        record
+      end
+    end
+
+    def _class_fetch_states
+      @_class_fetch_states ||= { all: 'n' }
+      @_class_fetch_states
+    end
+
+    def _class_observers
+      @_class_observers ||= Set.new
+      @_class_observers
+    end
+
+    def _class_state_key
+      @_class_state_key ||= self.to_s
+      @_class_state_key
+    end
+
+    def _notify_class_observers
+      _class_observers.each do |observer|
+        React::State.set_state(observer, _class_state_key, `Date.now() + Math.random()`)
+      end
+      _class_observers = Set.new
+    end
+
+    def _promise_get(uri)
+      Hyperloop::Resource::HTTP.get(uri, headers: { 'Content-Type' => 'application/json' })
+    end
+
+    def _promise_delete(uri)
+      Hyperloop::Resource::HTTP.delete(uri, headers: { 'Content-Type' => 'application/json' })
+    end
+
+    def _promise_patch(uri, payload)
+      Hyperloop::Resource::HTTP.patch(uri, payload: payload,
+                                 headers: { 'Content-Type' => 'application/json' },
+                                 dataType: :json)
+    end
+
+    def _promise_post(uri, payload)
+      Hyperloop::Resource::HTTP.post(uri, payload: payload,
+                                headers: { 'Content-Type' => 'application/json' },
+                                dataType: :json)
+    end
+
+    def _property_options
+      @property_options ||= {}
+    end
+
+    def _record_cache
+      @record_cache ||= {}
+    end
+
+    def _register_class_observer
+      observer = React::State.current_observer
+      if observer
+        React::State.get_state(observer, _class_state_key)
+        _class_observers << observer # @observers is a set, observers get added only once
+      end
+    end
+
+    def _rest_method_get_or_patch(name, id, *args)
+      uri = "#{resource_base_uri}/#{id}/methods/#{name}.json?timestamp=#{`Date.now() + Math.random()`}" # timestamp to invalidate browser caches
+      if args && args.size > 0
+        payload = { params: args }
+        _promise_patch(uri, payload).then do |result|
+          result.json[:result]
+        end
+      else
+        _promise_get(uri).then do |result|
+          result.json[:result]
+        end
+      end
+    end
+  end
+
+end