schemable 0.1.3 → 1.0.0

data/lib/schemable/relationship_schema_generator.rb

@@ -0,0 +1,119 @@
+module Schemable
+  # The RelationshipSchemaGenerator class is responsible for generating the 'relationships' part of a JSON:API compliant response.
+  # This class generates schemas for each relationship of a model, including 'belongs_to' (and has_many) and 'has_many' relationships.
+  #
+  # @see Schemable
+  class RelationshipSchemaGenerator
+    attr_reader :model_definition, :schema_modifier, :relationships
+
+    # Initializes a new RelationshipSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    #
+    # @example
+    #   generator = RelationshipSchemaGenerator.new(model_definition)
+    def initialize(model_definition)
+      @model_definition = model_definition
+      @schema_modifier = SchemaModifier.new
+      @relationships = model_definition.relationships
+    end
+
+    # Generates the 'relationships' part of the JSON:API response.
+    # It iterates over each relationship type (belongs_to, has_many) and for each relationship,
+    # it prepares a schema unless the relationship is excluded from expansion.
+    # If the 'expand' option is true, it changes the schema to include type and id properties inside the 'meta' property.
+    #
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from expansion.
+    # @param expand [Boolean] Whether to include the relationships of the related resource in the schema.
+    #
+    # @example
+    #   schema = generator.generate(expand: true, relationships_to_exclude_from_expansion: [:some_relationship])
+    #
+    # @return [Hash] The generated schema.
+    def generate(relationships_to_exclude_from_expansion: [], expand: false)
+      return {} if @relationships.blank? || @relationships == { belongs_to: {}, has_many: {} }
+
+      schema = {
+        type: :object,
+        properties: {}
+      }
+
+      %i[belongs_to has_many].each do |relation_type|
+        @relationships[relation_type]&.each do |relation, definition|
+          non_expanded_data_properties = {
+            type: :object,
+            properties: {
+              meta: {
+                type: :object,
+                properties: {
+                  included: { type: :boolean, default: false }
+                }
+              }
+            }
+          }
+
+          result = relation_type == :belongs_to ? generate_schema(definition.model_name) : generate_schema(definition.model_name, collection: true)
+
+          result = non_expanded_data_properties if !expand || relationships_to_exclude_from_expansion.include?(definition.model_name)
+
+          schema[:properties].merge!(relation => result)
+        end
+      end
+
+      # Modify the schema to include additional response relations
+      schema = @schema_modifier.add_properties(schema, @model_definition.additional_response_relations, 'properties')
+
+      # Modify the schema to exclude response relations
+      @model_definition.excluded_response_relations.each do |key|
+        schema = @schema_modifier.delete_properties(schema, "properties.#{key}")
+      end
+
+      schema
+    end
+
+    # Generates the schema for a specific relationship.
+    # If the 'collection' option is true, it generates a schema for a 'has_many' relationship,
+    # otherwise it generates a schema for a 'belongs_to' relationship. The difference between the two is that
+    # 'data' is an array in the 'has_many' relationship and an object in the 'belongs_to' relationship.
+    #
+    # @param type_name [String] The type of the related resource.
+    # @param collection [Boolean] Whether the relationship is a 'has_many' relationship.
+    #
+    # @example
+    #   relationship_schema = generator.generate_schema('resource_type', collection: true)
+    #
+    # @return [Hash] The generated schema for the relationship.
+    def generate_schema(type_name, collection: false)
+      if collection
+        {
+          type: :object,
+          properties: {
+            data: {
+              type: :array,
+              items: {
+                type: :object,
+                properties: {
+                  id: { type: :string },
+                  type: { type: :string, default: type_name }
+                }
+              }
+            }
+          }
+        }
+      else
+        {
+          type: :object,
+          properties: {
+            data: {
+              type: :object,
+              properties: {
+                id: { type: :string },
+                type: { type: :string, default: type_name }
+              }
+            }
+          }
+        }
+      end
+    end
+  end
+end

data/lib/schemable/request_schema_generator.rb

@@ -0,0 +1,88 @@
+module Schemable
+  # The RequestSchemaGenerator class is responsible for generating JSON schemas for create and update requests.
+  # This class generates schemas based on the model definition, including additional and excluded attributes.
+  #
+  # @see Schemable
+  class RequestSchemaGenerator
+    attr_reader :model_definition, :schema_modifier
+
+    # Initializes a new RequestSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    #
+    # @example
+    #   generator = RequestSchemaGenerator.new(model_definition)
+    def initialize(model_definition)
+      @model_definition = model_definition
+      @schema_modifier = SchemaModifier.new
+    end
+
+    # Generates the JSON schema for a create request.
+    # It generates a schema for the model attributes and then modifies it based on the additional and excluded attributes for create requests.
+    # It also determines the required attributes based on the optional and nullable attributes.
+    # Note that it is presumed that the model is using the same fields/columns for create as well as responses.
+    #
+    # @example
+    #   schema = generator.generate_for_create
+    #
+    # @return [Hash] The generated schema for create requests.
+    def generate_for_create
+      schema = {
+        type: :object,
+        properties: {
+          data: AttributeSchemaGenerator.new(@model_definition).generate
+        }
+      }
+
+      @schema_modifier.add_properties(schema, @model_definition.additional_create_request_attributes, 'properties.data.properties')
+
+      @model_definition.excluded_create_request_attributes.each do |key|
+        @schema_modifier.delete_properties(schema, "properties.data.properties.#{key}")
+      end
+
+      required_attributes = {
+        required: (
+          schema.as_json['properties']['data']['properties'].keys -
+          @model_definition.optional_create_request_attributes.map(&:to_s) -
+          @model_definition.nullable_attributes.map(&:to_s)
+        ).map { |key| key.to_s.camelize(:lower).to_sym }
+      }
+
+      @schema_modifier.add_properties(schema, required_attributes, 'properties.data')
+    end
+
+    # Generates the JSON schema for a update request.
+    # It generates a schema for the model attributes and then modifies it based on the additional and excluded attributes for update requests.
+    # It also determines the required attributes based on the optional and nullable attributes.
+    # Note that it is presumed that the model is using the same fields/columns for update as well as responses.
+    #
+    # @example
+    #   schema = generator.generate_for_update
+    #
+    # @return [Hash] The generated schema for update requests.
+    def generate_for_update
+      schema = {
+        type: :object,
+        properties: {
+          data: AttributeSchemaGenerator.new(@model_definition).generate
+        }
+      }
+
+      @schema_modifier.add_properties(schema, @model_definition.additional_update_request_attributes, 'properties.data.properties')
+
+      @model_definition.excluded_update_request_attributes.each do |key|
+        @schema_modifier.delete_properties(schema, "properties.data.properties.#{key}")
+      end
+
+      required_attributes = {
+        required: (
+          schema.as_json['properties']['data']['properties'].keys -
+            @model_definition.optional_update_request_attributes.map(&:to_s) -
+            @model_definition.nullable_attributes.map(&:to_s)
+        ).map { |key| key.to_s.camelize(:lower).to_sym }
+      }
+
+      @schema_modifier.add_properties(schema, required_attributes, 'properties.data')
+    end
+  end
+end

data/lib/schemable/response_schema_generator.rb

@@ -0,0 +1,124 @@
+module Schemable
+  # The ResponseSchemaGenerator class is responsible for generating JSON schemas for responses.
+  # This class generates schemas based on the model definition, including attributes, relationships, and included resources.
+  #
+  # @see Schemable
+  class ResponseSchemaGenerator
+    attr_reader :model_definition, :model, :schema_modifier, :configuration
+
+    # Initializes a new ResponseSchemaGenerator instance.
+    #
+    # @param model_definition [ModelDefinition] The model definition to generate the schema for.
+    #
+    # @example
+    #   generator = ResponseSchemaGenerator.new(model_definition)
+    def initialize(model_definition)
+      @model_definition = model_definition
+      @model = model_definition.model
+      @schema_modifier = SchemaModifier.new
+      @configuration = Schemable.configuration
+    end
+
+    # Generates the JSON schema for a response.
+    # It generates a schema for the model attributes and relationships, and if the 'expand' option is true,
+    # it also includes the included resources in the schema.
+    # It also adds meta and jsonapi information to the schema.
+    #
+    # @param expand [Boolean] Whether to include the included resources in the schema.
+    # @param relationships_to_exclude_from_expansion [Array] The relationships to exclude from expansion in the schema.
+    # @param collection [Boolean] Whether the response is for a collection of resources.
+    #
+    # @example
+    #   schema = generator.generate(expand: true, relationships_to_exclude_from_expansion: ['some_relationship'], collection: true)
+    #
+    # @return [Hash] The generated schema.
+    def generate(expand: false, relationships_to_exclude_from_expansion: [], collection: false)
+      data = {
+        type: :object,
+        properties: {
+          type: { type: :string, default: @model_definition.model_name },
+          id: { type: :string },
+          attributes: AttributeSchemaGenerator.new(@model_definition).generate
+        }.merge(
+          if @model_definition.relationships.blank? || @model_definition.relationships == { belongs_to: {}, has_many: {} }
+            {}
+          else
+            { relationships: RelationshipSchemaGenerator.new(@model_definition).generate(expand:, relationships_to_exclude_from_expansion:) }
+          end
+        )
+      }
+
+      schema = collection ? { data: { type: :array, items: data } } : { data: }
+
+      if expand
+        included_schema = IncludedSchemaGenerator.new(@model_definition).generate(expand:, relationships_to_exclude_from_expansion:)
+        @schema_modifier.add_properties(schema, included_schema, '.')
+      end
+
+      @schema_modifier.add_properties(schema, { meta: }, '.') if collection
+      @schema_modifier.add_properties(schema, { jsonapi: }, '.')
+
+      { type: :object, properties: schema }.compact_blank
+    end
+
+    # Generates the JSON schema for the 'meta' part of a response.
+    # It returns a custom meta response schema if one is defined in the configuration, otherwise it generates a default meta schema.
+    #
+    # @example
+    #   meta_schema = generator.meta
+    #
+    # @return [Hash] The generated schema for the 'meta' part of a response.
+    def meta
+      return @configuration.custom_meta_response_schema if @configuration.custom_meta_response_schema.present?
+
+      if @configuration.pagination_enabled
+        {
+          type: :object,
+          properties: {
+            page: {
+              type: :object,
+              properties: {
+                totalPages: {
+                  type: :integer,
+                  default: 1
+                },
+                count: {
+                  type: :integer,
+                  default: 1
+                },
+                rowsPerPage: {
+                  type: :integer,
+                  default: 1
+                },
+                currentPage: {
+                  type: :integer,
+                  default: 1
+                }
+              }
+            }
+          }
+        }
+      else
+        {}
+      end
+    end
+
+    # Generates the JSON schema for the 'jsonapi' part of a response.
+    #
+    # @example
+    #   jsonapi_schema = generator.jsonapi
+    #
+    # @return [Hash] The generated schema for the 'jsonapi' part of a response.
+    def jsonapi
+      {
+        type: :object,
+        properties: {
+          version: {
+            type: :string,
+            default: '1.0'
+          }
+        }
+      }
+    end
+  end
+end

data/lib/schemable/schema_modifier.rb

@@ -0,0 +1,248 @@
+module Schemable
+  # The SchemaModifier class provides methods for modifying a given schema.
+  # It includes methods for parsing paths, checking if a path exists in a schema,
+  # deeply merging hashes, adding properties to a schema, and deleting properties from a schema.
+  #
+  # @see Schemable
+  class SchemaModifier
+
+    # Parses a given path into an array of symbols.
+    #
+    # @note This method accepts paths in the following formats:
+    # - 'path.to.property'
+    # - 'path.to.array.[0].property'
+    #
+    # @example
+    #  parse_path('path.to.property') #=> [:path, :to, :property]
+    #  parse_path('path.to.array.[0].property') #=> [:path, :to, :array, :[0], :property]
+    #
+    # @param path [String] The path to parse.
+    # @return [Array<Symbol>] The parsed path.
+    def parse_path(path)
+      path.split('.').map(&:to_sym)
+    end
+
+    # Checks if a given path exists in a schema.
+    #
+    # @example
+    #   schema = {
+    #    path: {
+    #        type: :object,
+    #        properties: {
+    #          to: {
+    #            type: :object,
+    #            properties: {
+    #              property: {
+    #                type: :string
+    #              }
+    #            }
+    #          }
+    #        }
+    #     }
+    #   }
+    #
+    #  path = 'path.properties.to.properties.property'
+    #  incorrect_path = 'path.properties.to.properties.invalid'
+    #  path_exists?(schema, path) #=> true
+    #  path_exists?(schema, incorrect_path) #=> false
+    #
+    # @param schema [Hash, Array] The schema to check.
+    # @param path [String] The path to check for.
+    # @return [Boolean] True if the path exists in the schema, false otherwise.
+    def path_exists?(schema, path)
+      path_segments = parse_path(path)
+
+      path_segments.reduce(schema) do |current_segment, next_segment|
+        if current_segment.is_a?(Array)
+          # The regex pattern '/\[(\d+)\]|\d+/' matches square brackets containing one or more digits,
+          # or standalone digits. Used for parsing array indices in a path.
+          index = next_segment.to_s.match(/\[(\d+)\]|\d+/)[1]
+          # The regex pattern '/\A\d+\z/' matches a sequence of one or more digits from the start ('\A')
+          # to the end ('\z') of a string. It checks if a string consists of only digits.
+          return false if index.nil? || !index.match?(/\A\d+\z/) || index.to_i >= current_segment.length
+
+          current_segment[index.to_i]
+        else
+          return false unless current_segment.is_a?(Hash) && current_segment.key?(next_segment)
+
+          current_segment[next_segment]
+        end
+      end
+
+      true
+    end
+
+    # Deeply merges two hashes.
+    #
+    # @example
+    #   destination = { level1: { level2: { level3: 'value' } } }
+    #   new_data = { level1_again: 'value' }
+    #   deep_merge_hashes(destination, new_data)
+    #   #=> { level1: { level2: { level3: 'value' } }, level1_again: 'value' }
+    #
+    #   new_destination = [{ object1: 'value' }, { object2: 'value' }]
+    #   new_new_data = { object3: 'value' }
+    #   deep_merge_hashes(new_destination, new_new_data)
+    #   #=> [{ object1: 'value' }, { object2: 'value' }, { object3: 'value' }]
+    #
+    #   new_destination = { object1: 'value' }
+    #   new_new_data = [{ object2: 'value' }, { object3: 'value' }]
+    #   deep_merge_hashes(new_destination, new_new_data)
+    #   #=> { object1: 'value', object2: 'value', object3: 'value' }
+    #
+    # @param destination [Hash] The hash to merge into.
+    # @param new_data [Hash] The hash to merge from.
+    # @return [Hash] The merged hashes.
+    def deep_merge_hashes(destination, new_data)
+      if destination.is_a?(Hash) && new_data.is_a?(Array)
+        destination.merge(new_data)
+      elsif destination.is_a?(Array) && new_data.is_a?(Hash)
+        destination.push(new_data)
+      elsif destination.is_a?(Hash) && new_data.is_a?(Hash)
+        new_data.each do |key, value|
+          if destination[key].is_a?(Hash) && value.is_a?(Hash)
+            destination[key] = deep_merge_hashes(destination[key], value)
+          elsif destination[key].is_a?(Array) && value.is_a?(Array)
+            destination[key].concat(value)
+          elsif destination[key].is_a?(Array) && value.is_a?(Hash)
+            destination[key].push(value)
+          else
+            destination[key] = value
+          end
+        end
+      end
+
+      destination
+    end
+
+    # Adds properties to a schema at a given path.
+    #
+    # @example
+    #   original_schema = { level1: { level2: { level3: 'value' } } }
+    #   new_data = { L3: 'value' }
+    #   path = 'level1.level2'
+    #   add_properties(original_schema, new_schema, path)
+    #   #=> { level1: { level2: { level3: 'value', L3: 'value' } } }
+    #
+    #   new_original_schema = { test: [{ object1: 'value' }, { object2: 'value' }] }
+    #   new_new_schema = { object2_again: 'value' }
+    #   path = 'test.[1]'
+    #   add_properties(new_original_schema, new_new_schema, path)
+    #   #=> { test: [{ object1: 'value' }, { object2: 'value', object2_again: 'value' }] }
+    #
+    # @param original_schema [Hash] The original schema.
+    # @param new_schema [Hash] The new schema to add.
+    # @param path [String] The path at which to add the new schema.
+    # @note This method accepts paths in the following formats:
+    # - 'path.to.property'
+    # - 'path.to.array.[0].property'
+    # - '.'
+    #
+    # @return [Hash] The modified schema.
+    def add_properties(original_schema, new_schema, path)
+      return deep_merge_hashes(original_schema, new_schema) if path == '.'
+
+      unless path_exists?(original_schema, path)
+        puts "Error: Path '#{path}' does not exist in the original schema"
+        return original_schema
+      end
+
+      path_segments = parse_path(path)
+      current_segment = original_schema
+      last_segment = path_segments.pop
+
+      # Navigate to the specified location in the schema
+      path_segments.each do |segment|
+        if current_segment.is_a?(Array)
+          index = segment.to_s.match(/\[(\d+)\]|\d+/)[1]
+          if index&.match?(/\A\d+\z/) && index.to_i < current_segment.length
+            current_segment = current_segment[index.to_i]
+          else
+            puts "Error: Invalid index in path '#{path}'"
+            return original_schema
+          end
+        elsif current_segment.is_a?(Hash) && current_segment.key?(segment)
+          current_segment = current_segment[segment]
+        else
+          puts "Error: Expected a Hash but found #{current_segment.class} in path '#{path}'"
+          return original_schema
+        end
+      end
+
+      # Merge the new schema into the specified location
+      if current_segment.is_a?(Array)
+        index = last_segment.to_s.match(/\[(\d+)\]|\d+/)[1]
+        if index&.match?(/\A\d+\z/) && index.to_i < current_segment.length
+          current_segment[index.to_i] = deep_merge_hashes(current_segment[index.to_i], new_schema)
+        else
+          puts "Error: Invalid index in path '#{path}'"
+        end
+      else
+        current_segment[last_segment] = deep_merge_hashes(current_segment[last_segment], new_schema)
+      end
+
+      original_schema
+    end
+
+    # Deletes properties from a schema at a given path.
+    #
+    # @example
+    #   original_schema = { level1: { level2: { level3: 'value' } } }
+    #   path = 'level1.level2'
+    #   delete_properties(original_schema, path)
+    #   #=> { level1: {} }
+    #
+    #   new_original_schema = { test: [{ object1: 'value' }, { object2: 'value' }] }
+    #   path = 'test.[1]'
+    #   delete_properties(new_original_schema, path)
+    #   #=> { test: [{ object1: 'value' }] }
+    #
+    # @param original_schema [Hash] The original schema.
+    # @param path [String] The path at which to delete properties.
+    # @return [Hash] The modified schema.
+    def delete_properties(original_schema, path)
+      return original_schema if path == '.'
+
+      unless path_exists?(original_schema, path)
+        puts "Error: Path '#{path}' does not exist in the original schema"
+        return original_schema
+      end
+
+      path_segments = parse_path(path)
+      current_segment = original_schema
+      last_segment = path_segments.pop
+
+      # Navigate to the parent of the last segment in the path
+      path_segments.each do |segment|
+        if current_segment.is_a?(Array)
+          index = segment.to_s.match(/\[(\d+)\]|\d+/)[1]
+          if index&.match?(/\A\d+\z/) && index.to_i < current_segment.length
+            current_segment = current_segment[index.to_i]
+          else
+            puts "Error: Invalid index in path '#{path}'"
+            return original_schema
+          end
+        elsif current_segment.is_a?(Hash) && current_segment.key?(segment)
+          current_segment = current_segment[segment]
+        else
+          puts "Error: Expected a Hash but found #{current_segment.class} in path '#{path}'"
+          return original_schema
+        end
+      end
+
+      # Delete the last segment in the path
+      if current_segment.is_a?(Array)
+        index = last_segment.to_s.match(/\[(\d+)\]|\d+/)[1]
+        if index&.match?(/\A\d+\z/) && index.to_i < current_segment.length
+          current_segment.delete_at(index.to_i)
+        else
+          puts "Error: Invalid index in path '#{path}'"
+        end
+      else
+        current_segment.delete(last_segment)
+      end
+
+      original_schema
+    end
+  end
+end

data/lib/schemable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Schemable
-  VERSION = '0.1.3'
+  VERSION = '1.0.0'
 end