easy-jsonapi 1.0.0

data/lib/easy/jsonapi/request/query_param_collection/fields_param.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/query_param'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      # Used to create a unique Fieldset JSONAPI::Request::QueryParamCollection::QueryParam
+      class FieldsParam < QueryParam
+        
+        # @param fieldset_arr [Array<JSONAPI::Request::QueryParamCollection::FieldsParam::Fieldset>]
+        #   The array of fieldsets found in the query string. Ex: fields[resource]=res_field1,res_field2
+        def initialize(fieldset_arr)
+          super('fields', fieldset_arr)
+        end
+
+        # Alias to parent #value method
+        # @return [Array<JSONAPI::Request::QueryParamCollection::FieldsParam::Fieldset>]
+        def fieldsets
+          value
+        end
+
+        # @return The the query string representation of the included fieldsets
+        #   ex: "#{fieldset1.to_s}&{fieldset2.to_s}&..."
+        def to_s
+          JSONAPI::Utility.to_string_collection(value, delimiter: '&')
+        end
+  
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/fields_param/fieldset.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/name_value_pair_collection'
+require 'easy/jsonapi/request/query_param_collection/fields_param'
+require 'easy/jsonapi/utility'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < NameValuePairCollection
+      class FieldsParam < QueryParam
+        # Collection of fields related to specific resource objects
+        class Fieldset
+
+          attr_reader :resource_type, :fields
+
+          # @param field_arr [Array<JSONAPI::Field>]
+          #   A fieldset is a collection of Resource Fields
+          def initialize(resource_type, field_arr = [])
+            @resource_type = resource_type
+            @fields = field_arr
+          end
+
+          # Represention of Fieldset as a string where fields
+          #   are comma separated strings
+          def to_s
+            pre_string = "fields[#{@resource_type}]="
+            JSONAPI::Utility.to_string_collection(@fields, delimiter: ',', pre_string: pre_string)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/filter_param.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/query_param'
+require 'easy/jsonapi/utility'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      
+      # Used to create a unique Filter JSONAPI::Request::QueryParamCollection::QueryParam
+      class FilterParam < QueryParam
+        
+        # @param filter_arr [Array<JSONAPI::Request::QueryParamCollection::FilterParam::Filter>]
+        #   The array of filters included in the query string. Ex: filter[articles]=(posted_date == today)
+        def initialize(filter_arr)
+          super('filters', filter_arr)
+        end
+
+        # Represent each filter separated by a & value
+        #   Ex: "#{filter1.to_s}&{filter2.to_s}&..."
+        def to_s
+          JSONAPI::Utility.to_string_collection(value, delimiter: '&')
+        end
+
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/filter_param/filter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/filter_param'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < NameValuePairCollection
+      class FilterParam < QueryParam
+        # Represents an individual Filtering scheme for the filter query param(s) used.
+        class Filter
+
+          attr_reader :resource_type, :filter
+
+          # @param resource_type [String] The type to filter
+          # @param filter [String] The filter algorithm
+          def initialize(resource_type, filter)
+            @resource_type = resource_type
+            @filter = filter
+          end
+
+          # @return [String] The value of the filter
+          def value
+            @filter
+          end
+
+          # Represent filter as an individual filter query param
+          def to_s
+            "filter[#{@resource_type}]=#{@filter}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/include_param.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/query_param'
+require 'easy/jsonapi/utility'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      # The include query param
+      class IncludeParam < QueryParam
+        
+        
+        # @param includes_arr [Array<String>] An array with each individual query include
+        #   Ex: incude=author,people => ['author', 'people']
+        def initialize(includes_arr)
+          includes_hash_structure = store_includes(includes_arr)
+          super('includes', includes_hash_structure)
+        end
+
+        # to string
+        def to_s
+          "include=#{stringify_includes_hash(value)}"
+        end
+
+        private 
+
+        # Represent include internal hash as query string
+        # @param includes_hash [Hash] The internal structure
+        def stringify_includes_hash(includes_hash)
+          to_return = ''
+          first = true
+          includes_hash.each do |mem_name, mem_hash|
+            if first
+              to_return += to_s_mem(mem_name, mem_hash)
+              first = false
+            else
+              to_return += ",#{to_s_mem(mem_name, mem_hash)}"
+            end
+          end
+          to_return
+        end
+
+        # Depending on the delimiter stringify differently.
+        # @param mem_name [Symbol] The name of the member to stringify
+        # @param mem_hash [Hash] The information about that member
+        def to_s_mem(mem_name, mem_hash)
+          if mem_hash[:relationships] == {}
+            mem_name.to_s
+          else
+            delimiter = mem_hash[:included] == true ? '.' : '-'
+            prefix = "#{mem_name}#{delimiter}"
+            to_return = ''
+            first = true
+            mem_hash[:relationships].each do |m_name, m_hash|
+              if first
+                to_return += "#{prefix}#{to_s_mem(m_name, m_hash)}"
+                first = false
+              else
+                to_return += ",#{prefix}#{to_s_mem(m_name, m_hash)}"
+              end
+            end
+            to_return
+          end
+        end
+
+        # Helper for #initialize
+        # @param includes_arr [Array<String>] The array of includes to store
+        def store_includes(includes_arr)
+          incl_hash = {}
+          includes_arr.each do |include_str|
+            include_str_arr = include_str.scan(/\w+|-|\./) # split into array (word, -, or .)
+            store_include(incl_hash, include_str_arr)
+          end
+          incl_hash
+        end
+
+        # @param loc_in_h [Hash] The location within the main hash
+        # @param i_arr [Array<String>] The array of include strings
+        def store_include(loc_in_h, i_arr)
+          res_name = i_arr[0].to_sym
+          if i_arr.length == 1
+            add_member(loc_in_h, res_name, included: true)
+          else
+            add_member(loc_in_h, res_name, included: res_included?(i_arr))
+            store_include(loc_in_h[res_name][:relationships], i_arr[2..])
+          end
+        end
+
+        # @param (see #store_include)
+        def res_included?(i_arr)
+          delim = i_arr[1]
+          case delim
+          when '.'
+            true
+          when '-'
+            false
+          else
+            raise 'Syntax Error in include query string query param'
+          end
+        end
+
+        # @param loc_in_h [Hash] The location within the main hash
+        # @param res_name [Symbol] The name of the resource
+        # @param included [TrueClass | FalseClass] Whether or not a resource
+        #   is being requested or not
+        def add_member(loc_in_h, res_name, included:)
+          if loc_in_h.key?(res_name)
+            loc_in_h[res_name][:included] = included unless included == false
+          else
+            loc_in_h[res_name] = {
+              included: included,
+              relationships: {}
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/page_param.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/query_param'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      # Used to create a unique Page JSONAPI::Request::QueryParamCollection::QueryParam
+      class PageParam < QueryParam
+        
+        # @param offset [Integer | String] the page offset
+        # @param limit [Integer | String] the # of resources returned on a given page
+        def initialize(offset:, limit:)
+          super('page', { offset: offset.to_i, limit: limit.to_i })
+        end
+
+        # @raise [RuntimeError] Informs user to use a different method
+        def value
+          raise 'PageParam does not provide a #value method, try #offset or #limit instead'
+        end
+
+        # @raise [RuntimeError] Informs user to use a different method
+        def value=(_)
+          raise 'PageParam does not provide a #value= method, try #offset= or #limit= instead'
+        end
+
+        # @return [Integer] The page offset
+        def offset
+          @item[:value][:offset]
+        end
+  
+        # @param new_offset [Integer | String] The new page offset number
+        def offset=(new_offset)
+          @item[:value][:offset] = new_offset.to_i
+        end
+  
+        # @return [Integer] The # of resources returned on a given page
+        def limit
+          @item[:value][:limit]
+        end
+  
+        # @param new_limit [Integer] The new page limit number
+        def limit=(new_limit)
+          @item[:value][:limit] = new_limit.to_i
+        end
+  
+        # Represents the Page class in a string format
+        def to_s
+          "page[offset]=#{offset}&page[limit]=#{limit}"
+        end
+
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/request/query_param_collection/query_param.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection'
+require 'easy/jsonapi/name_value_pair'
+require 'easy/jsonapi/exceptions/query_params_exceptions'
+require 'easy/jsonapi/utility'
+
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      # A generic name=value query parameter
+      class QueryParam < JSONAPI::NameValuePair
+
+        # @param name [String] The name of the parameter
+        # @param value [String | Array<String>] The value of the parameter
+        def initialize(name, value)
+          if instance_of?(QueryParam)
+            JSONAPI::Exceptions::QueryParamsExceptions.check_param_name(name)
+          end
+          value = value.split(',') if value.is_a? String
+          super(name, value)
+        end
+  
+        # Update the query_param value, turning value into an array if it was given as a string
+        # @param new_value [String, Array<String>] The new value of the Parameter
+        def value=(new_value)
+          new_value = new_value.split(',') if new_value.is_a? String
+          super(new_value)
+        end
+        
+        # Represents a parameter as a string
+        def to_s
+          "#{name}=#{JSONAPI::Utility.to_string_collection(value, delimiter: ',')}"
+        end
+
+        # @raise RuntimeError Cannot change the name of a QueryParam object
+        def name=(_)
+          raise 'Cannot change the name of QueryParam Objects'
+        end
+      end
+    end
+  end
+end
+
+# include=author,comments-likers,comments.likes
+# author comments-likers comments.likes

data/lib/easy/jsonapi/request/query_param_collection/sort_param.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/request/query_param_collection/query_param'
+
+module JSONAPI
+  class Request
+    class QueryParamCollection < JSONAPI::NameValuePairCollection
+      # Used to create a unique Sort JSONAPI::Request::QueryParamCollection::QueryParam
+      class SortParam < QueryParam
+        
+        # @param res_field_arr [Array<JSONAPI::Field] The resource fields
+        #   to sort the primary resources by.
+        def initialize(res_field_arr)
+          super('sorts', res_field_arr)
+        end
+
+        # Represent sort as query string
+        def to_s
+          "sort=#{JSONAPI::Utility.to_string_collection(value, delimiter: ',')}"
+        end
+  
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/exceptions'
+
+module JSONAPI
+  # Used to validate the serialized response before returned to a client
+  module Response
+    # TODO: Add config_manager options for out bound serialization validation
+
+    # @param headers [Hash] The hash of response headers.
+    # @param body [Hash | String] The ruby hash mimicking jsonapi or
+    #   a JSON document to check for compliance
+    # @return [Nilclass] if no errors are found
+    # @raise [InvalidDocument | InvalidHeader] depending on what errors were found
+    def self.validate(headers, body)
+      # TODO: Spec checks based on collections which can be refered from the location header
+      #   returned by the server
+      JSONAPI::Exceptions::HeadersExceptions.check_compliance(headers.transform_keys(&:to_s).transform_keys(&:upcase))
+      JSONAPI::Exceptions::DocumentExceptions.check_compliance(body)
+    end
+  end
+end

data/lib/easy/jsonapi/utility.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  
+  # A collection of resued logic throughout the gem.
+  module Utility
+
+    class << self
+      
+      # To hash method for a JSONAPI collection (like Attributes)
+      # @param collection [Inumerable] The collection to hashify
+      def to_h_collection(collection)
+        to_return = {}
+        collection.each do |mem|
+          h_val = JSONAPI::Utility.to_h_value(mem)
+          to_return[mem.name.to_sym] = h_val
+        end
+        to_return
+      end
+      
+      # Helper method for #to_h_collection
+      # @param val [Any] The value to call to hash on.
+      # @return a hash value member
+      def to_h_value(val)
+        case val
+        when String
+          val
+        when JSONAPI::Collection
+          obj_hash = {}
+          val.each { |i| obj_hash[i.name.to_sym] = to_h_value(i) }
+          obj_hash
+        else
+          v = val.value
+          case v
+          when String
+            to_h_value(v)
+          when Array
+            v.map { |e| to_h_value(e) }
+          else
+            v.to_h
+          end
+        end
+      end
+      
+      # Helper for #to_h for classes that arent collection and have a set number
+      #   of instance variables to hashify
+      # @param hash_to_add_to [Hash] The hash to return
+      # @param obj_member [Any] The instance variable to hashify
+      # @param obj_member_name [Symbol] The hash key to store the object under
+      # @return [Hash] The hash for a specific instance variable
+      def to_h_member(hash_to_add_to, obj_member, obj_member_name)
+        return if obj_member.nil?
+        case obj_member
+        when String
+          hash_to_add_to[obj_member_name] = obj_member
+        when Array
+          hash_arr = obj_member.map(&:to_h)
+          hash_to_add_to[obj_member_name] = hash_arr
+        else
+          hash_to_add_to[obj_member_name] = obj_member.to_h
+        end
+      end
+      
+      # Helper method for #to_s that stringifys a collection
+      # @param collection [Inumerable] An array type of collection
+      # @param delimiter [String] The delimieter to separate each item string
+      # @param pre_string [String] The string to precede the collection string
+      # @param post_string [String] The string to follow the collection
+      def to_string_collection(collection, delimiter: ', ', pre_string: '', post_string: '')
+        to_return = pre_string
+        first = true
+        collection.each do |item|
+          if first
+            to_return += item.to_s
+            first = false
+          else
+            to_return += "#{delimiter}#{item}"
+          end
+        end
+        to_return += post_string
+      end
+      
+      # Helper for #to_s where collections are hashes and members should not
+      #   be included if they are nil. It also accounts for arrays.
+      # @param str_name [String | Symbol] The name of hash member
+      # @param member [Any] The value of the hash member 
+      # @param first_member [TrueClass | FalseClass] Whether or not this is the
+      #   first member in the hash.
+      def member_to_s(str_name, member, first_member: false)
+        return '' if member.nil?
+        member = "\"#{member}\"" if member.is_a? String
+        if first_member
+          "\"#{str_name}\": #{array_to_s(member)}"
+        else
+          ", \"#{str_name}\": #{array_to_s(member)}"
+        end
+      end
+      
+      # Returns the proper to_s for members regardless of 
+      #   whether they are stored as an array or member object
+      def array_to_s(obj_arr)
+        return obj_arr.to_s unless obj_arr.is_a? Array
+        to_return = '['
+        first = true
+        obj_arr.each do |obj|
+          if first
+            to_return += obj.to_s
+            first = false
+          else
+            to_return += ", #{obj}"
+          end
+        end
+        to_return += ']'
+      end
+      
+      # Get resource type from path
+      # @param path [String] The url path
+      # @return [String] The resource type
+      def path_to_res_type(path)
+        path_arr = path.split('/')
+        if integer?(path_arr[-1]) || uuid?(path_arr[-1])
+          path_arr[-2]
+        else
+          path_arr[-1]
+        end
+      end
+      
+      # Check if an input is an integer
+      # @param str [String | Integer]
+      def integer?(str)
+        # integers cannot be valid symbols, so assume string or integer input
+        return true if str.is_a?(Integer) ||
+                       str =~ /\A\d+\z/ 
+        false
+      end
+      
+      # Use regix to test whether the input is a valid gen 4 uuid.
+      # @param uuid [String]
+      # @return [TrueClass | FalseClass]
+      def uuid?(uuid)
+        # uuids cannot be valid symbols, so assume string
+        return true if uuid =~ /\A[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}\z/i ||
+                       uuid =~ /\A[\dA-F]{8}-[\dA-F]{4}-[\dA-F]{4}-[\dA-F]{4}-[\dA-F]{12}\z/i
+        false
+      end
+
+      # The hash method #dig throws an error if an array appears in the path specified,
+      #   this method returns false for such a senario.
+      # @param hash [Hash] The hash being inspected
+      # @param args [Array<Symbol | String>] The hash keys making up the path
+      def all_hash_path?(hash, args)
+        return false if (args.size.positive? && !hash.is_a?(Hash)) || hash.nil?
+        return true if args.size.zero? && !hash.nil?
+        all_hash_path?(hash[args.first], args[1..])
+      end
+    end
+  end
+end