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

jsonapi_compliable 0.6.4 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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