RubyGems - jsonapi_compliable - Versions diffs - 0.6.4 → 0.6.5 - Mend

jsonapi_compliable 0.6.4 → 0.6.5

Files changed (98) hide show

checksums.yaml +4 -4
data/.gitignore +1 -1
data/.travis.yml +11 -3
data/.yardopts +1 -0
data/README.md +10 -1
data/Rakefile +1 -0
data/docs/JsonapiCompliable.html +202 -0
data/docs/JsonapiCompliable/Adapters.html +119 -0
data/docs/JsonapiCompliable/Adapters/Abstract.html +2285 -0
data/docs/JsonapiCompliable/Adapters/ActiveRecord.html +2151 -0
data/docs/JsonapiCompliable/Adapters/ActiveRecordSideloading.html +582 -0
data/docs/JsonapiCompliable/Adapters/Null.html +1682 -0
data/docs/JsonapiCompliable/Base.html +1395 -0
data/docs/JsonapiCompliable/Deserializer.html +835 -0
data/docs/JsonapiCompliable/Errors.html +115 -0
data/docs/JsonapiCompliable/Errors/BadFilter.html +124 -0
data/docs/JsonapiCompliable/Errors/StatNotFound.html +266 -0
data/docs/JsonapiCompliable/Errors/UnsupportedPageSize.html +264 -0
data/docs/JsonapiCompliable/Errors/ValidationError.html +124 -0
data/docs/JsonapiCompliable/Extensions.html +117 -0
data/docs/JsonapiCompliable/Extensions/BooleanAttribute.html +212 -0
data/docs/JsonapiCompliable/Extensions/BooleanAttribute/ClassMethods.html +229 -0
data/docs/JsonapiCompliable/Extensions/ExtraAttribute.html +242 -0
data/docs/JsonapiCompliable/Extensions/ExtraAttribute/ClassMethods.html +237 -0
data/docs/JsonapiCompliable/Query.html +1099 -0
data/docs/JsonapiCompliable/Rails.html +211 -0
data/docs/JsonapiCompliable/Resource.html +5241 -0
data/docs/JsonapiCompliable/Scope.html +703 -0
data/docs/JsonapiCompliable/Scoping.html +117 -0
data/docs/JsonapiCompliable/Scoping/Base.html +843 -0
data/docs/JsonapiCompliable/Scoping/DefaultFilter.html +318 -0
data/docs/JsonapiCompliable/Scoping/ExtraFields.html +301 -0
data/docs/JsonapiCompliable/Scoping/Filter.html +313 -0
data/docs/JsonapiCompliable/Scoping/Filterable.html +364 -0
data/docs/JsonapiCompliable/Scoping/Paginate.html +613 -0
data/docs/JsonapiCompliable/Scoping/Sort.html +454 -0
data/docs/JsonapiCompliable/SerializableTempId.html +216 -0
data/docs/JsonapiCompliable/Sideload.html +2484 -0
data/docs/JsonapiCompliable/Stats.html +117 -0
data/docs/JsonapiCompliable/Stats/DSL.html +999 -0
data/docs/JsonapiCompliable/Stats/Payload.html +391 -0
data/docs/JsonapiCompliable/Util.html +117 -0
data/docs/JsonapiCompliable/Util/FieldParams.html +228 -0
data/docs/JsonapiCompliable/Util/Hash.html +471 -0
data/docs/JsonapiCompliable/Util/IncludeParams.html +299 -0
data/docs/JsonapiCompliable/Util/Persistence.html +435 -0
data/docs/JsonapiCompliable/Util/RelationshipPayload.html +563 -0
data/docs/JsonapiCompliable/Util/RenderOptions.html +250 -0
data/docs/JsonapiCompliable/Util/ValidationResponse.html +532 -0
data/docs/_index.html +527 -0
data/docs/class_list.html +51 -0
data/docs/css/common.css +1 -0
data/docs/css/full_list.css +58 -0
data/docs/css/style.css +492 -0
data/docs/file.README.html +99 -0
data/docs/file_list.html +56 -0
data/docs/frames.html +17 -0
data/docs/index.html +99 -0
data/docs/js/app.js +248 -0
data/docs/js/full_list.js +216 -0
data/docs/js/jquery.js +4 -0
data/docs/method_list.html +1731 -0
data/docs/top-level-namespace.html +110 -0
data/gemfiles/rails_5.gemfile +1 -1
data/lib/jsonapi_compliable/adapters/abstract.rb +267 -4
data/lib/jsonapi_compliable/adapters/active_record.rb +23 -1
data/lib/jsonapi_compliable/adapters/null.rb +43 -3
data/lib/jsonapi_compliable/base.rb +182 -33
data/lib/jsonapi_compliable/deserializer.rb +90 -21
data/lib/jsonapi_compliable/extensions/boolean_attribute.rb +12 -0
data/lib/jsonapi_compliable/extensions/extra_attribute.rb +32 -0
data/lib/jsonapi_compliable/extensions/temp_id.rb +11 -0
data/lib/jsonapi_compliable/query.rb +94 -2
data/lib/jsonapi_compliable/rails.rb +8 -0
data/lib/jsonapi_compliable/resource.rb +548 -11
data/lib/jsonapi_compliable/scope.rb +43 -1
data/lib/jsonapi_compliable/scoping/base.rb +59 -8
data/lib/jsonapi_compliable/scoping/default_filter.rb +33 -0
data/lib/jsonapi_compliable/scoping/extra_fields.rb +33 -0
data/lib/jsonapi_compliable/scoping/filter.rb +29 -2
data/lib/jsonapi_compliable/scoping/filterable.rb +4 -0
data/lib/jsonapi_compliable/scoping/paginate.rb +33 -0
data/lib/jsonapi_compliable/scoping/sort.rb +18 -0
data/lib/jsonapi_compliable/sideload.rb +229 -1
data/lib/jsonapi_compliable/stats/dsl.rb +44 -0
data/lib/jsonapi_compliable/stats/payload.rb +20 -0
data/lib/jsonapi_compliable/util/field_params.rb +1 -0
data/lib/jsonapi_compliable/util/hash.rb +18 -0
data/lib/jsonapi_compliable/util/include_params.rb +22 -0
data/lib/jsonapi_compliable/util/persistence.rb +13 -3
data/lib/jsonapi_compliable/util/relationship_payload.rb +2 -0
data/lib/jsonapi_compliable/util/render_options.rb +2 -0
data/lib/jsonapi_compliable/util/validation_response.rb +16 -0
data/lib/jsonapi_compliable/version.rb +1 -1
metadata +60 -5
data/gemfiles/rails_4.gemfile.lock +0 -208
data/gemfiles/rails_5.gemfile.lock +0 -212
data/lib/jsonapi_compliable/write.rb +0 -93

data/docs/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.9
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="JsonapiCompliable.html" title="JsonapiCompliable (module)">JsonapiCompliable</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Fri May  5 15:53:21 2017 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.9 (ruby-2.3.0).
+</div>
+    </div>
+  </body>
+</html>

data/gemfiles/rails_5.gemfile CHANGED Viewed

@@ -2,7 +2,7 @@
 source "https://rubygems.org"
-gem "rails", "~> 5.0"
+gem "rails", ['>= 5.0', '< 5.1']
 gem "jsonapi-rails", "~> 0.1", :require => "jsonapi/rails"
 gem "rspec-rails"

data/lib/jsonapi_compliable/adapters/abstract.rb CHANGED Viewed

@@ -1,33 +1,296 @@
 module JsonapiCompliable
   module Adapters
+    # Adapters DRY up common resource logic.
+    #
+    # For instance, there's no reason to write ActiveRecord logic like this in
+    # every Resource:
+    #
+    #   allow_filter :title do |scope, value|
+    #     scope.where(title: value)
+    #   end
+    #
+    #   sort do |scope, att, dir|
+    #     scope.order(att => dir)
+    #   end
+    #
+    #   paginate do |scope, current_page, per_page|
+    #     scope.page(current_page).per(per_page)
+    #   end
+    #
+    # This logic can be re-used through an *Adapter*:
+    #
+    #   use_adapter JsonapiCompliable::Adapters::ActiveRecord
+    #   allow_filter :title
+    #
+    # Adapters are pretty simple to write. The corresponding code for the above
+    # ActiveRecord adapter, which should look pretty familiar:
+    #
+    #   class JsonapiCompliable::Adapters::ActiveRecord
+    #     def filter(scope, attribute, value)
+    #       scope.where(attribute => value)
+    #     end
+    #
+    #     def order(scope, attribute, direction)
+    #       scope.order(attribute => direction)
+    #     end
+    #
+    #     def paginate(scope, current_page, per_page)
+    #       scope.page(current_page).per(per_page)
+    #     end
+    #   end
+    #
+    # An adapter can have a corresponding +sideloading_module+. This module
+    # gets mixed in to a Sideload. In other words, *Resource* is to
+    # *Adapter* as *Sideload* is to *Adapter#sideloading_module*. Use this
+    # module to define DSL methods that wrap #allow_sideload:
+    #
+    #   class MyAdapter < JsonapiCompliable::Adapters::Abstract
+    #     # ... code ...
+    #     def sideloading_module
+    #       MySideloadingAdapter
+    #     end
+    #   end
+    #
+    #   module MySideloadingAdapter
+    #     def belongs_to(association_name)
+    #       allow_sideload association_name do
+    #         # ... code ...
+    #       end
+    #     end
+    #   end
+    #
+    #   # And now in your Resource:
+    #   class MyResource < ApplicationResource
+    #     # ... code ...
+    #     use_adapter MyAdapter
+    #
+    #     belongs_to :my_association
+    #   end
+    #
+    # If you need the adapter to do *nothing*, because perhaps the API you
+    # are hitting does not support sorting,
+    # use +JsonapiCompliable::Adapters::Null+.
+    #
+    # @see Resource.use_adapter
+    # @see Adapters::ActiveRecord
+    # @see Adapters::ActiveRecordSideloading
+    # @see Adapters::Null
     class Abstract
+      # @param scope The scope object we are chaining
+      # @param [Symbol] attribute The attribute name we are filtering
+      # @param value The corresponding query parameter value
+      # @return the scope
+      #
+      # @example ActiveRecord default
+      #   def filter(scope, attribute, value)
+      #     scope.where(attribute => value)
+      #   end
       def filter(scope, attribute, value)
         raise 'you must override #filter in an adapter subclass'
       end
+      # @param scope The scope object we are chaining
+      # @param [Symbol] attribute The attribute name we are sorting
+      # @param [Symbol] direction The direction we are sorting (asc/desc)
+      # @return the scope
+      #
+      # @example ActiveRecord default
+      #   def order(scope, attribute, direction)
+      #     scope.order(attribute => direction)
+      #   end
       def order(scope, attribute, direction)
         raise 'you must override #order in an adapter subclass'
       end
-      def paginate(scope, number, size)
+      # @param scope The scope object we are chaining
+      # @param [Integer] current_page The current page number
+      # @param [Integer] per_page The number of results per page
+      # @return the scope
+      #
+      # @example ActiveRecord default
+      #   # via kaminari gem
+      #   def paginate(scope, current_page, per_page)
+      #     scope.page(current_page).per(per_page)
+      #   end
+      def paginate(scope, current_page, per_page)
         raise 'you must override #paginate in an adapter subclass'
       end
-      def sideload(scope, includes)
-        raise 'you must override #sideload in an adapter subclass'
+      # @param scope the scope object we are chaining
+      # @param [Symbol] attr corresponding stat attribute name
+      # @return [Numeric] the count of the scope
+      # @example ActiveRecord default
+      #   def count(scope, attr)
+      #     column = attr == :total ? :all : attr
+      #     scope.uniq.count(column)
+      #   end
+      def count(scope, attr)
+        raise 'you must override #count in an adapter subclass'
       end
-      def transaction
+      # @param scope the scope object we are chaining
+      # @param [Symbol] attr corresponding stat attribute name
+      # @return [Float] the average of the scope
+      # @example ActiveRecord default
+      #   def average(scope, attr)
+      #     scope.average(attr).to_f
+      #   end
+      def average(scope, attr)
+        raise 'you must override #average in an adapter subclass'
+      end
+      # @param scope the scope object we are chaining
+      # @param [Symbol] attr corresponding stat attribute name
+      # @return [Numeric] the sum of the scope
+      # @example ActiveRecord default
+      #   def sum(scope, attr)
+      #     scope.sum(attr)
+      #   end
+      def sum(scope, attr)
+        raise 'you must override #sum in an adapter subclass'
+      end
+      # @param scope the scope object we are chaining
+      # @param [Symbol] attr corresponding stat attribute name
+      # @return [Numeric] the maximum value of the scope
+      # @example ActiveRecord default
+      #   def maximum(scope, attr)
+      #     scope.maximum(attr)
+      #   end
+      def maximum(scope, attr)
+        raise 'you must override #maximum in an adapter subclass'
+      end
+      # @param scope the scope object we are chaining
+      # @param [Symbol] attr corresponding stat attribute name
+      # @return [Numeric] the maximum value of the scope
+      # @example ActiveRecord default
+      #   def maximum(scope, attr)
+      #     scope.maximum(attr)
+      #   end
+      def minimum(scope, attr)
+        raise 'you must override #maximum in an adapter subclass'
+      end
+      # This method must +yield+ the code to run within the transaction.
+      # This method should roll back the transaction if an error is raised.
+      #
+      # @param [Class] model_class The class we're operating on
+      # @example ActiveRecord default
+      #   def transaction(model_class)
+      #     model_class.transaction do
+      #       yield
+      #     end
+      #   end
+      #
+      # @see Resource.model
+      def transaction(model_class)
         raise 'you must override #transaction in an adapter subclass, it must yield'
       end
+      # Resolve the scope. This is where you'd actually fire SQL,
+      # actually make an HTTP call, etc.
+      #
+      # @example ActiveRecordDefault
+      #   def resolve(scope)
+      #     scope.to_a
+      #   end
+      #
+      # @example Suggested Customization
+      #   # When making a service call, we suggest this abstraction
+      #   # 'scope' here is a hash
+      #   def resolve(scope)
+      #     # The implementation of .where can be whatever you want
+      #     SomeModelClass.where(scope)
+      #   end
+      #
+      # @see Adapters::ActiveRecord#resolve
+      # @param scope The scope object to resolve
+      # @return an array of Model instances
       def resolve(scope)
         scope
       end
+      # Assign these two objects together.
+      #
+      # @example Basic accessor
+      #   def associate(parent, child, association_name, association_type)
+      #     if association_type == :has_many
+      #       parent.send(association_name).push(child)
+      #     else
+      #       child.send(:"#{association_name}=", parent)
+      #     end
+      #   end
+      #
+      # +association_name+ and +association_type+ come from your sideload
+      # configuration:
+      #
+      #   allow_sideload :the_name, type: the_type do
+      #     # ... code.
+      #   end
+      #
+      # @param parent The parent object (via the JSONAPI 'relationships' graph)
+      # @param child The child object (via the JSONAPI 'relationships' graph)
+      # @param association_name The 'relationships' key we are processing
+      # @param association_type The Sideload type (see Sideload#type). Usually :has_many/:belongs_to/etc
+      def associate(parent, child, association_name, association_type)
+        raise 'you must override #associate in an adapter subclass'
+      end
+      # This module gets mixed in to Sideload classes
+      # This is where you define methods like has_many,
+      # belongs_to etc that wrap the lower-level Sideload#allow_sideload
+      #
+      # @see Resource#allow_sideload
+      # @see Sideload#allow_sideload
+      # @see Adapters::ActiveRecord#sideloading_module
+      # @see Adapters::ActiveRecordSideloading
+      # @return the module to mix in
       def sideloading_module
         Module.new
       end
+      # @param [Class] model_class The configured model class (see Resource.model)
+      # @param [Hash] create_params Attributes + id
+      # @return the model instance just created
+      # @see Resource.model
+      # @example ActiveRecord default
+      #   def create(model_class, create_params)
+      #     instance = model_class.new(create_params)
+      #     instance.save
+      #     instance
+      #   end
+      def create(model_class, create_params)
+        raise 'you must override #create in an adapter subclass'
+      end
+      # @param [Class] model_class The configured model class (see Resource.model)
+      # @param [Hash] update_params Attributes + id
+      # @return the model instance just created
+      # @see Resource.model
+      # @example ActiveRecord default
+      #   def update(model_class, update_params)
+      #     instance = model_class.find(update_params.delete(:id))
+      #     instance.update_attributes(update_params)
+      #     instance
+      #   end
+      def update(model_class, update_params)
+        raise 'you must override #update in an adapter subclass'
+      end
+      # @param [Class] model_class The configured model class (see Resource.model)
+      # @param [Integer] id the id for this model
+      # @return the model instance just destroyed
+      # @see Resource.model
+      # @example ActiveRecord default
+      #   def destroy(model_class, id)
+      #     instance = model_class.find(id)
+      #     instance.destroy
+      #     instance
+      #   end
+      def destroy(model_class, id)
+        raise 'you must override #destroy in an adapter subclass'
+      end
     end
   end
 end

data/lib/jsonapi_compliable/adapters/active_record.rb CHANGED Viewed

@@ -2,53 +2,72 @@ require 'jsonapi_compliable/adapters/active_record_sideloading'
 module JsonapiCompliable
   module Adapters
+    # @see Adapters::Abstract
     class ActiveRecord < Abstract
+      # (see Adapters::Abstract#filter)
       def filter(scope, attribute, value)
         scope.where(attribute => value)
       end
+      # (see Adapters::Abstract#order)
       def order(scope, attribute, direction)
         scope.order(attribute => direction)
       end
+      # (see Adapters::Abstract#paginate)
       def paginate(scope, current_page, per_page)
         scope.page(current_page).per(per_page)
       end
+      # (see Adapters::Abstract#count)
       def count(scope, attr)
-        scope.uniq.count
+        column = attr == :total ? :all : attr
+        scope.uniq.count(column)
       end
+      # (see Adapters::Abstract#average)
       def average(scope, attr)
         scope.average(attr).to_f
       end
+      # (see Adapters::Abstract#sum)
       def sum(scope, attr)
         scope.sum(attr)
       end
+      # (see Adapters::Abstract#maximum)
       def maximum(scope, attr)
         scope.maximum(attr)
       end
+      # (see Adapters::Abstract#minimum)
       def minimum(scope, attr)
         scope.minimum(attr)
       end
+      # (see Adapters::Abstract#resolve)
       def resolve(scope)
         scope.to_a
       end
+      # Run this write request within an ActiveRecord transaction
+      # @param [Class] model_class The ActiveRecord class we are saving
+      # @return Result of yield
+      # @see Adapters::Abstract#transaction
       def transaction(model_class)
         model_class.transaction do
           yield
         end
       end
+      # (see Adapters::Abstract#sideloading_module)
       def sideloading_module
         JsonapiCompliable::Adapters::ActiveRecordSideloading
       end
+      # When a has_many relationship, we need to avoid Activerecord implicitly
+      # firing a query. Otherwise, simple assignment will do
+      # @see Adapters::Abstract#associate
       def associate(parent, child, association_name, association_type)
         if association_type == :has_many
           parent.association(association_name).loaded!
@@ -58,18 +77,21 @@ module JsonapiCompliable
         end
       end
+      # (see Adapters::Abstract#create)
       def create(model_class, create_params)
         instance = model_class.new(create_params)
         instance.save
         instance
       end
+      # (see Adapters::Abstract#update)
       def update(model_class, update_params)
         instance = model_class.find(update_params.delete(:id))
         instance.update_attributes(update_params)
         instance
       end
+      # (see Adapters::Abstract#destroy)
       def destroy(model_class, id)
         instance = model_class.find(id)
         instance.destroy