jsonapi_compliable 0.6.4 → 0.6.5

data/lib/jsonapi_compliable/stats/dsl.rb

@@ -1,8 +1,34 @@
 module JsonapiCompliable
   module Stats
+    # Provides an easier interface to stats scoping.
+    #
+    # Used within Resource DSL:
+    #
+    #   allow_stat total: [:count] do
+    #     # ... eval'd in Stats::DSL context! ...
+    #   end
+    #
+    # This allows us to define arbitrary stats:
+    #
+    #   allow_stat total: [:count] do
+    #     standard_deviation { |scope, attr| ... }
+    #   end
+    #
+    # And use convenience methods:
+    #
+    #   allow_stat :rating do
+    #     count!
+    #     average!
+    #   end
+    #
+    # @see Resource.allow_stat
+    # @attr_reader [Symbol] name the stat, e.g. :total
+    # @attr_reader [Hash] calculations procs for various metrics
     class DSL
       attr_reader :name, :calculations
 
+      # @param [Adapters::Abstract] adapter the Resource adapter
+      # @param [Symbol, Hash] config example: +:total+ or +{ total: [:count] }+
       def initialize(adapter, config)
         config = { config => [] } if config.is_a?(Symbol)
 
@@ -12,31 +38,49 @@ module JsonapiCompliable
         Array(config.values.first).each { |c| send(:"#{c}!") }
       end
 
+      # Used for defining arbitrary stats within the DSL:
+      #
+      #   allow_stat :total do
+      #     standard_deviation { |scope, attr| ... }
+      #   end
+      #
+      # ...will hit +method_missing+ and store the proc for future reference.
+      # @api private
       def method_missing(meth, *args, &blk)
         @calculations[meth] = blk
       end
 
+      # Grab a calculation proc. Raises error if no corresponding stat
+      # has been configured.
+      #
+      # @param [String, Symbol] name the name of the calculation, e.g. +:total+
+      # @return [Proc] the proc to run the calculation
       def calculation(name)
         callable = @calculations[name] || @calculations[name.to_sym]
         callable || raise(Errors::StatNotFound.new(@name, name))
       end
 
+      # Convenience method for default :count proc
       def count!
         @calculations[:count] = @adapter.method(:count)
       end
 
+      # Convenience method for default :sum proc
       def sum!
         @calculations[:sum] = @adapter.method(:sum)
       end
 
+      # Convenience method for default :average proc
       def average!
         @calculations[:average] = @adapter.method(:average)
       end
 
+      # Convenience method for default :maximum proc
       def maximum!
         @calculations[:maximum] = @adapter.method(:maximum)
       end
 
+      # Convenience method for default :minimum proc
       def minimum!
         @calculations[:minimum] = @adapter.method(:minimum)
       end

data/lib/jsonapi_compliable/stats/payload.rb

@@ -1,12 +1,32 @@
 module JsonapiCompliable
   module Stats
+    # Generate the stats payload so we can return it in the response.
+    #
+    #   {
+    #     data: [...],
+    #     meta: { stats: the_generated_payload }
+    #   }
+    #
+    # For example:
+    #
+    #   {
+    #     data: [...],
+    #     meta: { stats: { total: { count: 100 } } }
+    #   }
     class Payload
+      # @param [Resource] resource the resource instance
+      # @param [Hash] query_hash the Query#to_hash for the current resource
+      # @param scope the scope we are chaining/modifying
       def initialize(resource, query_hash, scope)
         @resource   = resource
         @query_hash = query_hash[:stats]
         @scope      = scope
       end
 
+      # Generate the payload for +{ meta: { stats: { ... } } }+
+      # Loops over all calculations, computes then, and gives back
+      # a hash of stats and their results.
+      # @return [Hash] the generated payload
       def generate
         {}.tap do |stats|
           @query_hash.each_pair do |name, calculation|

data/lib/jsonapi_compliable/util/field_params.rb

@@ -1,5 +1,6 @@
 module JsonapiCompliable
   module Util
+    # @api private
     class FieldParams
       def self.parse(params)
         return {} if params.nil?

data/lib/jsonapi_compliable/util/hash.rb

@@ -1,6 +1,19 @@
 module JsonapiCompliable
   module Util
+    # @api private
     class Hash
+      # Grab all keys at any level of the hash.
+      #
+      #   { foo: { bar: { baz: {} } } }
+      #
+      # Becomes
+      #
+      # [:foo, :bar, :bar]
+      #
+      # @param hash the hash we want to process
+      # @param [Array<Symbol, String>] collection the memoized collection of keys
+      # @return [Array<Symbol, String>] the keys
+      # @api private
       def self.keys(hash, collection = [])
         hash.each_pair do |key, value|
           collection << key
@@ -10,11 +23,16 @@ module JsonapiCompliable
         collection
       end
 
+      # Like ActiveSupport's #deep_merge
+      # @return [Hash] the merged hash
+      # @api private
       def self.deep_merge!(hash, other)
         merger = proc { |key, v1, v2| Hash === v1 && Hash === v2 ? v1.merge(v2, &merger) : v2 }
         hash.merge!(other, &merger)
       end
 
+      # Like ActiveSupport's #deep_dup
+      # @api private
       def self.deep_dup(hash)
         if hash.respond_to?(:deep_dup)
           hash.deep_dup

data/lib/jsonapi_compliable/util/include_params.rb

@@ -1,7 +1,29 @@
 module JsonapiCompliable
   module Util
+    # Utility class for dealing with Include Directives
     class IncludeParams
       class << self
+        # Let's say the user requested these sideloads:
+        #
+        #   GET /posts?include=comments.author
+        #
+        # But our resource had this code:
+        #
+        #   sideload_whitelist({ index: [:comments] })
+        #
+        # We should drop the 'author' sideload from the request.
+        #
+        # Hashes become 'include directive hashes' within the library. ie
+        #
+        #   [:tags, { comments: :author }]
+        #
+        # Becomes
+        #
+        #   { tags: {}, comments: { author: {} } }
+        #
+        # @param [Hash] requested_includes the nested hash the user requested
+        # @param [Hash] allowed_includes the nested hash configured via DSL
+        # @return [Hash] the scrubbed hash
         def scrub(requested_includes, allowed_includes)
           {}.tap do |valid|
             requested_includes.each_pair do |key, sub_hash|

data/lib/jsonapi_compliable/util/persistence.rb

@@ -1,4 +1,10 @@
+# Save the given Resource#model, and all of its nested relationships.
+# @api private
 class JsonapiCompliable::Util::Persistence
+  # @param [Resource] resource the resource instance
+  # @param [Hash] meta see (Deserializer#meta)
+  # @param [Hash] attributes see (Deserializer#attributes)
+  # @param [Hash] relationships see (Deserializer#relationships)
   def initialize(resource, meta, attributes, relationships)
     @resource      = resource
     @meta          = meta
@@ -6,9 +12,11 @@ class JsonapiCompliable::Util::Persistence
     @relationships = relationships
   end
 
+  # Perform the actual save logic.
+  #
   # belongs_to must be processed before/separately from has_many -
   # we need to know the primary key value of the parent before
-  # persisting the child
+  # persisting the child.
   #
   # Flow:
   # * process parents
@@ -19,6 +27,8 @@ class JsonapiCompliable::Util::Persistence
   # * process children
   # * associate children
   # * return current object
+  #
+  # @return the persisted model instance
   def run
     parents = process_belongs_to(@relationships)
     update_foreign_key_for_parents(parents)
@@ -35,6 +45,8 @@ class JsonapiCompliable::Util::Persistence
     persisted unless @meta[:method] == :destroy
   end
 
+  private
+
   # The child's attributes should be modified to nil-out the
   # foreign_key when the parent is being destroyed or disassociated
   def update_foreign_key(parent_object, attrs, x)
@@ -99,8 +111,6 @@ class JsonapiCompliable::Util::Persistence
     object.instance_variable_set(:@_jsonapi_temp_id, temp_id)
   end
 
-  private
-
   def iterate(only: [], except: [])
     opts = {
       resource: @resource,

data/lib/jsonapi_compliable/util/relationship_payload.rb

@@ -1,5 +1,7 @@
 module JsonapiCompliable
   module Util
+    # Helper methods for traversing the 'relationships' JSONAPI payloads
+    # @api private
     class RelationshipPayload
       attr_reader :resource, :payload
 

data/lib/jsonapi_compliable/util/render_options.rb

@@ -1,5 +1,7 @@
 module JsonapiCompliable
   module Util
+    # Generate the options we end up passing to {{http://jsonapi-rb.org jsonapi-rb}}
+    # @api private
     class RenderOptions
       def self.generate(object, query_hash, overrides = {})
         resolved = object.respond_to?(:resolve) ? object.resolve : object

data/lib/jsonapi_compliable/util/validation_response.rb

@@ -1,15 +1,31 @@
+# We need to know two things in the response of a persistence call:
+#
+#   * The model we just tried to persist
+#   * Was the persistence successful?
+#
+# This object wraps those bits of data. The call is considered
+# unsuccessful when it adheres to the ActiveModel#errors interface,
+# and #errors is not blank. In other words, it is not successful if
+# there were validation errors.
+#
+# @attr_reader object the object we are saving
 class JsonapiCompliable::Util::ValidationResponse
   attr_reader :object
 
+  # @param object the model instance we tried to save
+  # @param deserialized_params see Base#deserialized_params
   def initialize(object, deserialized_params)
     @object = object
     @deserialized_params = deserialized_params
   end
 
+  # Check to ensure no validation errors.
+  # @return [Boolean] did the persistence call succeed?
   def success?
     all_valid?(object, @deserialized_params.relationships)
   end
 
+  # @return [Array] the object and success state
   def to_a
     [object, success?]
   end

data/lib/jsonapi_compliable/version.rb

@@ -1,3 +1,3 @@
 module JsonapiCompliable
-  VERSION = "0.6.4"
+  VERSION = "0.6.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_compliable
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.6.5
 platform: ruby
 authors:
 - Lee Richmond
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-26 00:00:00.000000000 Z
+date: 2017-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsonapi-serializable
@@ -127,6 +127,7 @@ files:
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Appraisals
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -138,10 +139,65 @@ files:
 - bin/console
 - bin/rspec
 - bin/setup
+- docs/JsonapiCompliable.html
+- docs/JsonapiCompliable/Adapters.html
+- docs/JsonapiCompliable/Adapters/Abstract.html
+- docs/JsonapiCompliable/Adapters/ActiveRecord.html
+- docs/JsonapiCompliable/Adapters/ActiveRecordSideloading.html
+- docs/JsonapiCompliable/Adapters/Null.html
+- docs/JsonapiCompliable/Base.html
+- docs/JsonapiCompliable/Deserializer.html
+- docs/JsonapiCompliable/Errors.html
+- docs/JsonapiCompliable/Errors/BadFilter.html
+- docs/JsonapiCompliable/Errors/StatNotFound.html
+- docs/JsonapiCompliable/Errors/UnsupportedPageSize.html
+- docs/JsonapiCompliable/Errors/ValidationError.html
+- docs/JsonapiCompliable/Extensions.html
+- docs/JsonapiCompliable/Extensions/BooleanAttribute.html
+- docs/JsonapiCompliable/Extensions/BooleanAttribute/ClassMethods.html
+- docs/JsonapiCompliable/Extensions/ExtraAttribute.html
+- docs/JsonapiCompliable/Extensions/ExtraAttribute/ClassMethods.html
+- docs/JsonapiCompliable/Query.html
+- docs/JsonapiCompliable/Rails.html
+- docs/JsonapiCompliable/Resource.html
+- docs/JsonapiCompliable/Scope.html
+- docs/JsonapiCompliable/Scoping.html
+- docs/JsonapiCompliable/Scoping/Base.html
+- docs/JsonapiCompliable/Scoping/DefaultFilter.html
+- docs/JsonapiCompliable/Scoping/ExtraFields.html
+- docs/JsonapiCompliable/Scoping/Filter.html
+- docs/JsonapiCompliable/Scoping/Filterable.html
+- docs/JsonapiCompliable/Scoping/Paginate.html
+- docs/JsonapiCompliable/Scoping/Sort.html
+- docs/JsonapiCompliable/SerializableTempId.html
+- docs/JsonapiCompliable/Sideload.html
+- docs/JsonapiCompliable/Stats.html
+- docs/JsonapiCompliable/Stats/DSL.html
+- docs/JsonapiCompliable/Stats/Payload.html
+- docs/JsonapiCompliable/Util.html
+- docs/JsonapiCompliable/Util/FieldParams.html
+- docs/JsonapiCompliable/Util/Hash.html
+- docs/JsonapiCompliable/Util/IncludeParams.html
+- docs/JsonapiCompliable/Util/Persistence.html
+- docs/JsonapiCompliable/Util/RelationshipPayload.html
+- docs/JsonapiCompliable/Util/RenderOptions.html
+- docs/JsonapiCompliable/Util/ValidationResponse.html
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
 - gemfiles/rails_4.gemfile
-- gemfiles/rails_4.gemfile.lock
 - gemfiles/rails_5.gemfile
-- gemfiles/rails_5.gemfile.lock
 - jsonapi_compliable.gemspec
 - lib/jsonapi_compliable.rb
 - lib/jsonapi_compliable/adapters/abstract.rb
@@ -176,7 +232,6 @@ files:
 - lib/jsonapi_compliable/util/render_options.rb
 - lib/jsonapi_compliable/util/validation_response.rb
 - lib/jsonapi_compliable/version.rb
-- lib/jsonapi_compliable/write.rb
 homepage: 
 licenses:
 - MIT

data/gemfiles/rails_4.gemfile.lock

@@ -1,208 +0,0 @@
-PATH
-  remote: ..
-  specs:
-    jsonapi_compliable (0.6.3)
-      jsonapi-serializable (~> 0.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    actionmailer (4.2.7.1)
-      actionpack (= 4.2.7.1)
-      actionview (= 4.2.7.1)
-      activejob (= 4.2.7.1)
-      mail (~> 2.5, >= 2.5.4)
-      rails-dom-testing (~> 1.0, >= 1.0.5)
-    actionpack (4.2.7.1)
-      actionview (= 4.2.7.1)
-      activesupport (= 4.2.7.1)
-      rack (~> 1.6)
-      rack-test (~> 0.6.2)
-      rails-dom-testing (~> 1.0, >= 1.0.5)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (4.2.7.1)
-      activesupport (= 4.2.7.1)
-      builder (~> 3.1)
-      erubis (~> 2.7.0)
-      rails-dom-testing (~> 1.0, >= 1.0.5)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    activejob (4.2.7.1)
-      activesupport (= 4.2.7.1)
-      globalid (>= 0.3.0)
-    activemodel (4.2.7.1)
-      activesupport (= 4.2.7.1)
-      builder (~> 3.1)
-    activerecord (4.2.7.1)
-      activemodel (= 4.2.7.1)
-      activesupport (= 4.2.7.1)
-      arel (~> 6.0)
-    activesupport (4.2.7.1)
-      i18n (~> 0.7)
-      json (~> 1.7, >= 1.7.7)
-      minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
-      tzinfo (~> 1.1)
-    appraisal (2.1.0)
-      bundler
-      rake
-      thor (>= 0.14.0)
-    arel (6.0.3)
-    builder (3.2.2)
-    byebug (9.0.6)
-    coderay (1.1.1)
-    concurrent-ruby (1.0.4)
-    database_cleaner (1.5.3)
-    diff-lcs (1.2.5)
-    erubis (2.7.0)
-    ffi (1.9.14)
-    formatador (0.2.5)
-    globalid (0.3.7)
-      activesupport (>= 4.1.0)
-    guard (2.14.0)
-      formatador (>= 0.2.4)
-      listen (>= 2.7, < 4.0)
-      lumberjack (~> 1.0)
-      nenv (~> 0.1)
-      notiffany (~> 0.0)
-      pry (>= 0.9.12)
-      shellany (~> 0.0)
-      thor (>= 0.18.1)
-    guard-compat (1.2.1)
-    guard-rspec (4.7.3)
-      guard (~> 2.1)
-      guard-compat (~> 1.1)
-      rspec (>= 2.99.0, < 4.0)
-    i18n (0.7.0)
-    json (1.8.3)
-    jsonapi-deserializable (0.1.1)
-      jsonapi-parser (= 0.1.1)
-    jsonapi-parser (0.1.1)
-    jsonapi-rails (0.1.1)
-      jsonapi-rb (= 0.1.1)
-    jsonapi-rb (0.1.1)
-      jsonapi-deserializable (= 0.1.1)
-      jsonapi-serializable (= 0.1.1)
-    jsonapi-renderer (0.1.1)
-    jsonapi-serializable (0.1.1)
-      jsonapi-renderer (= 0.1.1)
-    kaminari (0.17.0)
-      actionpack (>= 3.0.0)
-      activesupport (>= 3.0.0)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
-    loofah (2.0.3)
-      nokogiri (>= 1.5.9)
-    lumberjack (1.0.10)
-    mail (2.6.4)
-      mime-types (>= 1.16, < 4)
-    method_source (0.8.2)
-    mime-types (3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2016.0521)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
-    nenv (0.3.0)
-    nokogiri (1.6.8.1)
-      mini_portile2 (~> 2.1.0)
-    notiffany (0.1.1)
-      nenv (~> 0.1)
-      shellany (~> 0.0)
-    pry (0.10.4)
-      coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
-    pry-byebug (3.4.2)
-      byebug (~> 9.0)
-      pry (~> 0.10)
-    rack (1.6.5)
-    rack-test (0.6.3)
-      rack (>= 1.0)
-    rails (4.2.7.1)
-      actionmailer (= 4.2.7.1)
-      actionpack (= 4.2.7.1)
-      actionview (= 4.2.7.1)
-      activejob (= 4.2.7.1)
-      activemodel (= 4.2.7.1)
-      activerecord (= 4.2.7.1)
-      activesupport (= 4.2.7.1)
-      bundler (>= 1.3.0, < 2.0)
-      railties (= 4.2.7.1)
-      sprockets-rails
-    rails-deprecated_sanitizer (1.0.3)
-      activesupport (>= 4.2.0.alpha)
-    rails-dom-testing (1.0.7)
-      activesupport (>= 4.2.0.beta, < 5.0)
-      nokogiri (~> 1.6.0)
-      rails-deprecated_sanitizer (>= 1.0.1)
-    rails-html-sanitizer (1.0.3)
-      loofah (~> 2.0)
-    railties (4.2.7.1)
-      actionpack (= 4.2.7.1)
-      activesupport (= 4.2.7.1)
-      rake (>= 0.8.7)
-      thor (>= 0.18.1, < 2.0)
-    rake (10.5.0)
-    rb-fsevent (0.9.8)
-    rb-inotify (0.9.7)
-      ffi (>= 0.5.0)
-    rspec (3.5.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.4)
-      rspec-support (~> 3.5.0)
-    rspec-expectations (3.5.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-mocks (3.5.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-rails (3.5.2)
-      actionpack (>= 3.0)
-      activesupport (>= 3.0)
-      railties (>= 3.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
-      rspec-support (~> 3.5.0)
-    rspec-support (3.5.0)
-    ruby_dep (1.5.0)
-    shellany (0.0.1)
-    slop (3.6.0)
-    sprockets (3.7.0)
-      concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    sprockets-rails (3.2.0)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
-      sprockets (>= 3.0.0)
-    sqlite3 (1.3.12)
-    thor (0.19.4)
-    thread_safe (0.3.5)
-    tzinfo (1.2.2)
-      thread_safe (~> 0.1)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  activerecord (>= 4.1, < 6)
-  appraisal
-  bundler (~> 1.12)
-  database_cleaner
-  guard
-  guard-rspec
-  jsonapi-rails (~> 0.1)
-  jsonapi_compliable!
-  kaminari (~> 0.17)
-  pry
-  pry-byebug
-  rails (~> 4.1)
-  rake (~> 10.0)
-  rspec-rails
-  sqlite3
-
-BUNDLED WITH
-   1.14.6