hyper-resource 1.0.0.lap79 → 1.0.0.lap80

data/lib/hyper_record/client_instance_methods.rb

@@ -1,6 +1,9 @@
 module HyperRecord
   module ClientInstanceMethods
 
+    # initialize a new instance of current HyperRecord class
+    #
+    # @param record_hash [Hash] optional, initial values for properties
     def initialize(record_hash = {})
       # initalize internal data structures
       record_hash = {} if record_hash.nil?
@@ -57,23 +60,40 @@ module HyperRecord
       self.class._record_cache[@properties[:id].to_s] = self if @properties.has_key?(:id)
     end
 
-    ### reactive api
+    ### high level api
 
+    # destroy record, success is assumed
+    #
+    # @return nil
     def destroy
       promise_destroy
       nil
     end
 
+    # check if record has been destroyed
+    #
+    # @return [Boolean]
     def destroyed?
       @destroyed
     end
 
+    # link the two records using a relation determined by other_record.class, success is assumed
+    #
+    # @param other_record [HyperRecord]
+    # @return [HyperRecord] self
     def link(other_record)
       _register_observer
       promise_link(other_record)
       self
     end
 
+    # method_missing is used for undeclared properties like in ActiveRecord models
+    #
+    # Two call signatures:
+    # 1. the getter:
+    # a_model.a_undeclared_property, returns the value of a_undeclared_property
+    # 2. the setter:
+    # a_model.a_undeclared_property = value, set a_undeclared_property to value, returns value
     def method_missing(method, arg)
       _register_observer
       if method.end_with?('=')
@@ -87,25 +107,40 @@ module HyperRecord
       end
     end
 
+    # introspection
+    # @return [Hash]
     def reflections
       self.class.reflections
     end
 
+    # reset properties to last saved value
+    #
+    # @return [HyperRecord] self
     def reset
       _register_observer
       @changed_properties = {}
+      self
     end
 
+    # get the resource base uri that is used for api calls, used internally
+    #
+    # @return [String]
     def resource_base_uri
       self.class.resource_base_uri
     end
 
+    # save record to db, success is assumed
+    #
+    # @return [HyperRecord] self
     def save
       _register_observer
       promise_save
       self
     end
 
+    # return record properties as Hash
+    #
+    # @return [Hash]
     def to_hash
       _register_observer
       res = @properties.dup
@@ -113,11 +148,17 @@ module HyperRecord
       res
     end
 
+    # return record properties as String
+    #
+    # @return [String]
     def to_s
       _register_observer
       @properties.to_s
     end
 
+    # unlink the two records using a relation determined by other_record.class, success is assumed
+    #
+    # @return [HyperRecord] self
     def unlink(other_record)
       _register_observer
       promise_unlink(other_record)
@@ -126,9 +167,13 @@ module HyperRecord
 
     ### promise api
 
+    # destroy record
+    #
+    # @return [Promise] on success the record is passed to the .then block
+    #   on failure the HTTP response is passed to the .fail block
     def promise_destroy
       _local_destroy
-      self.class._promise_delete("#{resource_base_uri}/#{@properties[:id]}").then do |response|
+      self.class._promise_delete("#{resource_base_uri}/#{@properties[:id]}").then do |record|
         self
       end.fail do |response|
         error_message = "Destroying record #{self} failed!"
@@ -137,6 +182,11 @@ module HyperRecord
       end
     end
 
+    # link the two records using a relation determined by other_record.class
+    #
+    # @param other_record [HyperRecord]
+    # @return [Promise] on success the record is passed to the .then block
+    #   on failure the HTTP response is passed to the .fail block
     def promise_link(other_record, relation_name = nil)
       called_from_collection = relation_name ? true : false
       relation_name = other_record.class.to_s.underscore.pluralize unless relation_name
@@ -174,6 +224,10 @@ module HyperRecord
       end
     end
 
+    # save record
+    #
+    # @return [Promise] on success the record is passed to the .then block
+    #   on failure the HTTP response is passed to the .fail block
     def promise_save
       payload_hash = @properties.merge(@changed_properties) # copy hash, because we need to delete some keys
       (%i[id created_at updated_at] + reflections.keys).each do |key|
@@ -203,6 +257,11 @@ module HyperRecord
       end
     end
 
+    # unlink the two records using a relation determined by other_record.class
+    #
+    # @param other_record [HyperRecord]
+    # @return [Promise] on success the record is passed to the .then block
+    #   on failure the HTTP response is passed to the .fail block
     def promise_unlink(other_record, relation_name = nil)
       called_from_collection = collection_name ? true : false
       relation_name = other_record.class.to_s.underscore.pluralize unless relation_name
@@ -210,6 +269,7 @@ module HyperRecord
       @relations[relation_name].delete_if { |cr| cr == other_record } if !called_from_collection && @fetch_states[relation_name] == 'f'
       self.class._promise_delete("#{resource_base_uri}/#{@properties[:id]}/relations/#{relation_name}.json?record_id=#{other_record.id}").then do |response|
         _notify_observers
+        other_record._notify_observers
         self
       end.fail do |response|
         error_message = "Unlinking #{other_record} from #{self} failed!"
@@ -219,7 +279,7 @@ module HyperRecord
     end
 
     ### internal
-
+    # @private
     def _local_destroy
       _register_observer
       @destroyed = true
@@ -231,6 +291,7 @@ module HyperRecord
       _notify_observers
     end
 
+    # @private
     def _notify_observers
       @observers.each do |observer|
         React::State.set_state(observer, @state_key, `Date.now() + Math.random()`)
@@ -239,10 +300,12 @@ module HyperRecord
       self.class._notify_class_observers
     end
 
+    # @private
     def _register_collection(collection)
       @registered_collections << collection
     end
 
+    # @private
     def _register_observer
       observer = React::State.current_observer
       if observer
@@ -251,10 +314,12 @@ module HyperRecord
       end
     end
 
+    # @private
     def _unregister_collection(collection)
       @registered_collections.delete(collection)
     end
 
+    # @private
     def _update_record(data)
       if data.has_key?(:relation)
         if data.has_key?(:cause)

data/lib/hyper_record/collection.rb

@@ -1,17 +1,26 @@
 module HyperRecord
   class Collection < Array
-    def initialize(array, record = nil, relation_name = nil)
+
+    # initialize new HyperRecord::Collection, used internally
+    #
+    # @param collection [HyperRecord::Collection] or [Array] of records or empty [Array]
+    # @param record [HyperRecord] optional base record this collection belongs to
+    # @param relation_name [String] optional base record relation name this collection represents
+    def initialize(collection = [], record = nil, relation_name = nil)
       @record = record
       @relation_name = relation_name
-      if array
-        array.each do |record|
+      if collection
+        collection.each do |record|
           record._register_collection(self)
         end
       end
       @record._notify_observers if @record
-      array ? super(array) : super
+      collection ? super(collection) : super
     end
 
+    # add record to collection, record is saved to db, success assumed
+    #
+    # @param other_record [HyperRecord] record to add
     def <<(other_record)
       if @record && @relation_name
         @record.promise_link(other_record, @relation_name)
@@ -21,6 +30,9 @@ module HyperRecord
       super(other_record)
     end
 
+    # delete record from collection, saved to db, success assumed
+    #
+    # @param other_record [HyperRecord] record to delete from collection
     def delete(other_record)
       if @record && @relation_name && !other_record.instance_variable_get(:@remotely_destroyed)
         @record.promise_unlink(other_record, @relation_name)
@@ -30,6 +42,9 @@ module HyperRecord
       super(other_record)
     end
 
+    # add record to collection, not saved to db
+    #
+    # @param other_record [HyperRecord] record to add
     def push(other_record)
       other_record._register_collection(self)
       @record._notify_observers if @record

data/lib/hyper_record/pub_sub.rb

@@ -9,6 +9,7 @@ module HyperRecord
     module ClassMethods
       attr_accessor :policy_params
 
+      # @private
       def _pusher_client
         Hyperloop.pusher_instance ||= Pusher::Client.new(
           app_id: Hyperloop.pusher[:app_id],
@@ -18,6 +19,9 @@ module HyperRecord
         )
       end
 
+      # send message about record change to all subscribers of this record
+      #
+      # @param record of ORM specific type, record must respond to: id, updated_at, destroyed?
       def publish_record(record)
         subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{record.class}__#{record.id}")
         time_now = Time.now.to_f
@@ -47,6 +51,11 @@ module HyperRecord
         Hyperloop.redis_instance.del("HRPS__#{record.class}__#{record.id}") if record.destroyed?
       end
 
+      # send message about relation change to all subscribers of this record
+      #
+      # @param base_record of ORM specific type, base_record must respond to: id, updated_at, destroyed?
+      # @param relation_name [String]
+      # @param record of ORM specific type, the record who causes the change, record must respond to: id, updated_at, destroyed?
       def publish_relation(base_record, relation_name, record = nil)
         subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{base_record.class}__#{base_record.id}__#{relation_name}")
         time_now = Time.now.to_f
@@ -79,6 +88,10 @@ module HyperRecord
         end
       end
 
+      # send message to notify clients that they should call the rest_class_method again
+      #
+      # @param record_class ORM specific
+      # @param rest_class_method_name [String]
       def publish_rest_class_method(record_class, rest_class_method_name)
         subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{record_class}__rest_class_method__#{rest_class_method_name}")
         time_now = Time.now.to_f
@@ -102,20 +115,24 @@ module HyperRecord
         end
       end
 
-      def publish_rest_method(record, method_name)
-        subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{record.class}__#{record.id}__rest_method__#{method_name}")
+      # send message to notify clients that they should call the rest_method again
+      #
+      # @param record of ORM specific type
+      # @param rest_method_name [String]
+      def publish_rest_method(record, rest_method_name)
+        subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{record.class}__#{record.id}__rest_method__#{rest_method_name}")
         time_now = Time.now.to_f
         scrub_time = time_now - 24.hours.to_f
         message = {
           record_type: record.class.to_s,
           id: record.id,
-          rest_method: method_name
+          rest_method: rest_method_name
         }
         subscribers.each_slice(10) do |slice|
           channel_array = []
           slice.each do |session_id, last_requested|
             if last_requested.to_f < scrub_time
-              Hyperloop.redis_instance.hdel("HRPS__#{record.class}__#{record.id}__rest_method__#{method_name}", session_id)
+              Hyperloop.redis_instance.hdel("HRPS__#{record.class}__#{record.id}__rest_method__#{rest_method_name}", session_id)
               next
             end
             channel_array << "hyper-record-update-channel-#{session_id}"
@@ -126,6 +143,10 @@ module HyperRecord
         end
       end
 
+      # send message about scope change to all subscribers
+      #
+      # @param record_class ORM specific
+      # @param scope_name [String]
       def publish_scope(record_class, scope_name)
         subscribers = Hyperloop.redis_instance.hgetall("HRPS__#{record_class}__scope__#{scope_name}")
         time_now = Time.now.to_f
@@ -149,11 +170,19 @@ module HyperRecord
         end
       end
 
+      # subscribe to record changes
+      #
+      # @param record of ORM specific type
       def subscribe_record(record)
         return unless session.id
         Hyperloop.redis_instance.hset "HRPS__#{record.class}__#{record.id}", session.id.to_s, Time.now.to_f.to_s
       end
 
+      # subscribe to relation changes
+      #
+      # @param relation [Enumarable] or record of ORM specific type, subscribe to each member of relation
+      # @param base_record optional, of ORM specific type, subscribe to this base_record too
+      # @param relation_name [String] optional name of the relation
       def subscribe_relation(relation, base_record = nil, relation_name = nil)
         return unless session.id
         time_now = Time.now.to_f.to_s
@@ -172,6 +201,10 @@ module HyperRecord
         end
       end
 
+      # subscribe to rest_class_method updates
+      #
+      # @param record_class ORM specific
+      # @param rest_class_method_name [String] name of the rest_class_method
       def subscribe_rest_class_method(record_class, rest_class_method_name)
         return unless session.id
         time_now = Time.now.to_f.to_s
@@ -181,6 +214,10 @@ module HyperRecord
         end
       end
 
+      # subscribe to rest_method updates
+      #
+      # @param record of ORM specific type
+      # @param rest_method_name [String] name of the rest_method
       def subscribe_rest_method(record, rest_method_name)
         return unless session.id
         time_now = Time.now.to_f.to_s
@@ -188,6 +225,11 @@ module HyperRecord
         Hyperloop.redis_instance.hset("HRPS__#{record.class}__#{record.id}__rest_method__#{rest_method_name}", session_id, time_now)
       end
 
+      # subscribe to scope updates
+      #
+      # @param collection [Enumerable] subscribe to each member of collection
+      # @param record_class optional, ORM specific
+      # @param scope_name [String] optional
       def subscribe_scope(collection, record_class = nil, scope_name = nil)
         return unless session.id
         time_now = Time.now.to_f.to_s
@@ -202,94 +244,132 @@ module HyperRecord
         end
       end
 
+      # subscribe to record and then publish
+      #
+      # @param record of ORM psecific type
       def pub_sub_record(record)
         subscribe_record(record)
         publish_record(record)
       end
 
+      # subscribe to relation changes and then publish them
+      #
+      # @param relation [Enumarable] or record of ORM specific type, subscribe to each member of relation
+      # @param base_record of ORM specific type, base_record must respond to: id, updated_at, destroyed?
+      # @param relation_name [String]
+      # @param causing_record of ORM specific type the record who causes the change, reacord must respond to: id, updated_at, destroyed?
       def pub_sub_relation(relation, base_record, relation_name, causing_record = nil)
         subscribe_relation(relation, base_record, relation_name)
         publish_relation(base_record, relation_name, causing_record)
       end
 
+      # subscribe to rest_class_method and then send message to notify clients that
+      # they should call the rest_class_method again
+      #
+      # @param record_class ORM specific
+      # @param rest_class_method_name [String]
       def pub_sub_rest_class_method(record_class, rest_class_method_name)
         subscribe_rest_class_method(record_class, rest_class_method_name)
         publish_rest_class_method(record_class, rest_class_method_name)
       end
 
+      # subscribe to rest_method and then send message to notify clients that
+      # they should call the rest_method again
+      #
+      # @param record of ORM specific type
+      # @param rest_method_name [String]
       def pub_sub_rest_method(record, rest_method_name)
         subscribe_rest_method(record, rest_method_name)
         publish_rest_method(record, rest_method_name)
       end
 
+      # subscribe to scope changes and send message about scope change to all subscribers
+      #
+      # @param collection [Enumerable] subscribe to each member of collection
+      # @param record_class ORM specific
+      # @param scope_name [String]
       def pub_sub_scope(collection, record_class, scope_name)
         subscribe_scope(collection, record_class, scope_name)
         publish_scope(record_class, scope_name)
       end
 
+      # @private
       def session
         @_hyper_resource_session
       end
     end
 
-    # instance methods
-
+    # (see ClassMethods#publish_record)
     def publish_record(record)
       self.class.publish_record(record)
     end
 
+    # (see ClassMethods#publish_relation)
     def publish_relation(base_record, relation_name, record = nil)
       self.class.publish_relation(base_record, relation_name, record)
     end
 
+    # (see ClassMethods#publish_rest_class_method)
     def publish_rest_class_method(record_class, rest_class_method_name)
       self.class.publish_rest_class_method(record_class, rest_class_method_name)
     end
 
-    def publish_rest_method(record, method_name)
-      self.class.publish_rest_method(record, method_name)
+    # (see ClassMethods#publish_rest_method)
+    def publish_rest_method(record, rest_method_name)
+      self.class.publish_rest_method(record, rest_method_name)
     end
 
+    # (see ClassMethods#publish_scope)
     def publish_scope(record_class, scope_name)
       self.class.publish_scope(record_class, scope_name)
     end
 
+    # (see ClassMethods#subscribe_record)
     def subscribe_record(record)
       self.class.subscribe_record(record)
     end
 
+    # (see ClassMethods#subscribe_relation)
     def subscribe_relation(relation, base_record = nil, relation_name = nil)
       self.class.subscribe_relation(relation, base_record, relation_name)
     end
 
+    # (see ClassMethods#subscribe_rest_class_method)
     def subscribe_rest_class_method(record_class, rest_class_method_name)
       self.class.subscribe_rest_class_method(record_class, rest_class_method_name)
     end
 
-    def subscribe_rest_method(record, method_name)
-      self.class.subscribe_rest_method(record, method_name)
+    # (see ClassMethods#subscribe_rest_method)
+    def subscribe_rest_method(record, rest_method_name)
+      self.class.subscribe_rest_method(record, rest_method_name)
     end
 
+    # (see ClassMethods#subscribe_scope)
     def subscribe_scope(collection, record_class = nil, scope_name = nil)
       self.class.subscribe_scope(collection, record_class, scope_name)
     end
 
+    # (see ClassMethods#pub_sub_record)
     def pub_sub_record(record)
       self.class.pub_sub_record(record)
     end
 
+    # (see ClassMethods#pub_sub_relation)
     def pub_sub_relation(relation, base_record, relation_name, causing_record = nil)
       self.class.pub_sub_relation(relation, base_record, relation_name, causing_record)
     end
 
+    # (see ClassMethods#pub_sub_rest_class_method)
     def pub_sub_rest_class_method(record_class, rest_class_method_name)
       self.class.pub_sub_rest_class_method(record_class, rest_class_method_name)
     end
 
-    def pub_sub_rest_method(record, method_name)
-      self.class.pub_sub_rest_method(record, method_name)
+    # (see ClassMethods#pub_sub_rest_method)
+    def pub_sub_rest_method(record, rest_method_name)
+      self.class.pub_sub_rest_method(record, rest_method_name)
     end
 
+    # (see ClassMethods#pub_sub_scope)
     def pub_sub_scope(collection, record_class, scope_name)
       self.class.pub_sub_scope(collection, record_class, scope_name)
     end

data/lib/hyper_record/server_class_methods.rb

@@ -1,5 +1,8 @@
 module HyperRecord
   module ServerClassMethods
+    # DSL for defining rest_class_methods
+    # @param name [Symbol] name of the method
+    # @param options [Hash] known key: default_result, used client side
     def rest_class_method(name, options = { default_result: '...' }, &block)
       rest_class_methods[name] = options
       rest_class_methods[name][:params] = block.arity
@@ -12,6 +15,9 @@ module HyperRecord
       end
     end
 
+    # DSL for defining rest_methods
+    # @param name [Symbol] name of the method
+    # @param options [Hash] known key: default_result, used client side
     def rest_method(name, options = { default_result: '...' }, &block)
       rest_methods[name] = options
       rest_methods[name][:params] = block.arity
@@ -24,18 +30,27 @@ module HyperRecord
       end
     end
 
+    # introspect defined rest_class_methods
+    # @return [Hash]
     def rest_class_methods
       @rest_class_methods ||= {}
     end
 
+    # introspect defined rest_methods
+    # @return [Hash]
     def rest_methods
       @rest_methods ||= {}
     end
 
+    # introspect defined scopes
+    # @return [Hash]
     def resource_scopes
       @resource_scopes ||= []
     end
 
+    # defines a scope, wrapper around ORM method
+    # @param name [Symbol] name of the args
+    # @param *args additional args, passed to ORMs scope DSL
     def scope(name, *args)
       resource_scopes << name
       super(name, *args)

data/lib/hyperloop/resource/client_drivers.rb

@@ -49,6 +49,7 @@ module Hyperloop
 
       else
 
+        # @private
         def self.initialize_client_drivers_on_boot
 
           return if @initialized
@@ -90,6 +91,7 @@ module Hyperloop
           end
         end
 
+        # @private
         def self.process_notification(data)
           record_class = Object.const_get(data[:record_type])
           if data[:scope]