verquest 0.1.0 → 0.2.0

data/lib/verquest/properties/collection.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Collection property type for arrays of objects
+    #
+    # Represents an array of complex objects in the schema.
+    # Used for defining collections of structured data objects.
+    #
+    # @example Define a collection of items with inline properties
+    #   products = Verquest::Properties::Collection.new(name: :products)
+    #   products.add(Verquest::Properties::Field.new(name: :id, type: :string, required: true))
+    #   products.add(Verquest::Properties::Field.new(name: :name, type: :string))
+    #
+    # @example Define a collection referencing an existing schema
+    #   products = Verquest::Properties::Collection.new(
+    #     name: :products,
+    #     item: ProductRequest
+    #   )
+    class Collection < Base
+      # Initialize a new Collection property
+      #
+      # @param name [Symbol] The name of the property
+      # @param item [Verquest::Base, nil] Optional reference to an external schema class
+      # @param required [Boolean] Whether this property is required
+      # @param map [String, nil] The mapping path for this property
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      # @raise [ArgumentError] If attempting to map a collection to the root
+      def initialize(name:, item: nil, required: false, map: nil, **schema_options)
+        raise ArgumentError, "You can not map collection to the root" if map == "/"
+
+        @properties = {}
+
+        @name = name
+        @item = item
+        @required = required
+        @map = map
+        @schema_options = schema_options
+      end
+
+      # Add a child property to this collection's item definition
+      #
+      # @param property [Verquest::Properties::Base] The property to add to the collection items
+      # @return [Verquest::Properties::Base] The added property
+      def add(property)
+        properties[property.name] = property
+      end
+
+      # Check if this collection references an external item schema
+      #
+      # @return [Boolean] True if the collection uses an external reference
+      def has_item?
+        !item.nil?
+      end
+
+      # Generate JSON schema definition for this collection property
+      #
+      # @return [Hash] The schema definition for this collection property
+      def to_schema
+        if has_item?
+          {
+            name => {
+              type: :array,
+              items: {
+                "$ref": item.to_ref
+              }
+            }.merge(schema_options)
+          }
+        else
+          {
+            name => {
+              type: :array,
+              items: {
+                type: :object,
+                required: properties.values.select(&:required).map(&:name),
+                properties: properties.transform_values { |property| property.to_schema[property.name] }
+              }
+            }.merge(schema_options)
+          }
+        end
+      end
+
+      # Generate validation schema for this collection property
+      #
+      # @param version [String, nil] The version to generate validation schema for
+      # @return [Hash] The validation schema for this collection property
+      def to_validation_schema(version: nil)
+        if has_item?
+          {
+            name => {
+              type: :array,
+              items: item.to_validation_schema(version: version)
+            }.merge(schema_options)
+          }
+        else
+          {
+            name => {
+              type: :array,
+              items: {
+                type: :object,
+                required: properties.values.select(&:required).map(&:name),
+                properties: properties.transform_values { |property| property.to_validation_schema(version: version)[property.name] }
+              }
+            }.merge(schema_options)
+          }
+        end
+      end
+
+      # Create mapping for this collection property and all its children
+      #
+      # This method handles two different scenarios:
+      # 1. When the collection references an external item schema (`has_item?` returns true)
+      #    - Creates mappings by transforming keys from the referenced item schema
+      #    - Adds array notation ([]) to indicate this is a collection
+      #    - Prefixes all keys and values with the appropriate paths
+      #
+      # 2. When the collection has inline item properties
+      #    - Creates mappings for each property in the collection items
+      #    - Each property gets mapped with array notation and appropriate prefixes
+      #
+      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String, nil] The version to create mapping for
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version:)
+        if has_item?
+          value_key_prefix = mapping_value_key(value_prefix: value_prefix, collection: true)
+
+          reference_mapping = item.mapping(version:).dup
+          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join(".")}[].#{_1}" }
+          reference_mapping.transform_values! { "#{value_key_prefix}.#{_1}" }
+
+          mapping.merge!(reference_mapping)
+        else
+          properties.values.each do |property|
+            property.mapping(key_prefix: key_prefix + ["#{name}[]"], value_prefix: mapping_value_prefix(value_prefix: value_prefix, collection: true), mapping:, version:)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :item, :schema_options, :properties
+    end
+  end
+end

data/lib/verquest/properties/field.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Field property type for basic scalar values
+    #
+    # Represents simple scalar types (string, number, integer, boolean) in the schema.
+    # Used for defining basic data fields without nesting.
+    #
+    # @example Define a required string field
+    #   field = Verquest::Properties::Field.new(
+    #     name: :email,
+    #     type: :string,
+    #     required: true,
+    #     format: "email"
+    #   )
+    class Field < Base
+      # List of allowed field types
+      # @return [Array<Symbol>]
+      ALLOWED_TYPES = %i[string number integer boolean].freeze
+
+      # Initialize a new Field property
+      #
+      # @param name [Symbol] The name of the property
+      # @param type [Symbol] The data type for this field, must be one of ALLOWED_TYPES
+      # @param required [Boolean] Whether this property is required
+      # @param map [String, nil] The mapping path for this property
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      # @raise [ArgumentError] If type is not one of the allowed types
+      # @raise [ArgumentError] If attempting to map a field to root without a name
+      def initialize(name:, type:, required: false, map: nil, **schema_options)
+        raise ArgumentError, "Type must be one of #{ALLOWED_TYPES.join(", ")}" unless ALLOWED_TYPES.include?(type)
+        raise ArgumentError, "You can not map fields to the root without a name" if map == "/"
+
+        @name = name
+        @type = type
+        @required = required
+        @map = map
+        @schema_options = schema_options
+      end
+
+      # Generate JSON schema definition for this field
+      #
+      # @return [Hash] The schema definition for this field
+      def to_schema
+        {name => {type: type}.merge(schema_options)}
+      end
+
+      # Create mapping for this field property
+      #
+      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String, nil] The version to create mapping for
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
+        mapping[(key_prefix + [name]).join(".")] = mapping_value_key(value_prefix:)
+      end
+
+      private
+
+      attr_reader :type, :schema_options
+    end
+  end
+end

data/lib/verquest/properties/object.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Object property type for structured data
+    #
+    # Represents a complex object with nested properties in the schema.
+    # Used for defining structured data objects with multiple fields.
+    #
+    # @example Define an address object with nested properties
+    #   address = Verquest::Properties::Object.new(name: :address)
+    #   address.add(Verquest::Properties::Field.new(name: :street, type: :string))
+    #   address.add(Verquest::Properties::Field.new(name: :city, type: :string, required: true))
+    class Object < Base
+      # Initialize a new Object property
+      #
+      # @param name [String] The name of the property
+      # @param required [Boolean] Whether this property is required
+      # @param map [String, nil] The mapping path for this property
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      def initialize(name:, required: false, map: nil, **schema_options)
+        @properties = {}
+
+        @name = name
+        @required = required
+        @map = map
+        @schema_options = schema_options
+      end
+
+      # Add a child property to this object
+      #
+      # @param property [Verquest::Properties::Base] The property to add to this object
+      # @return [Verquest::Properties::Base] The added property
+      def add(property)
+        properties[property.name] = property
+      end
+
+      # Generate JSON schema definition for this object property
+      #
+      # @return [Hash] The schema definition for this object property
+      def to_schema
+        {
+          name => {
+            type: :object,
+            required: properties.values.select(&:required).map(&:name),
+            properties: properties.transform_values { |property| property.to_schema[property.name] }
+          }.merge(schema_options)
+        }
+      end
+
+      # Generate validation schema for this object property
+      #
+      # @param version [String, nil] The version to generate validation schema for
+      # @return [Hash] The validation schema for this object property
+      def to_validation_schema(version: nil)
+        {
+          name => {
+            type: :object,
+            required: properties.values.select(&:required).map(&:name),
+            properties: properties.transform_values { |property| property.to_validation_schema(version:)[property.name] }
+          }.merge(schema_options)
+        }
+      end
+
+      # Create mapping for this object property and all its children
+      #
+      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String, nil] The version to create mapping for
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version: nil)
+        properties.values.each do |property|
+          property.mapping(key_prefix: key_prefix + [name], value_prefix: mapping_value_prefix(value_prefix:), mapping:, version:)
+        end
+      end
+
+      private
+
+      attr_reader :type, :schema_options, :properties
+    end
+  end
+end

data/lib/verquest/properties/reference.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Reference property type for schema reuse
+    #
+    # Allows referencing other schema definitions to promote reuse and DRY principles.
+    # Can reference either a complete schema or a specific property within a schema.
+    #
+    # @example Reference another schema
+    #   reference = Verquest::Properties::Reference.new(
+    #     name: :user,
+    #     from: UserRequest,
+    #     required: true
+    #   )
+    #
+    # @example Reference a specific property from another schema
+    #   reference = Verquest::Properties::Reference.new(
+    #     name: :address,
+    #     from: UserRequest,
+    #     property: :address
+    #   )
+    class Reference < Base
+      # Initialize a new Reference property
+      #
+      # @param name [String] The name of the property
+      # @param from [Class] The schema class to reference
+      # @param property [Symbol, nil] Optional specific property to reference
+      # @param map [String, nil] The mapping path for this property
+      # @param required [Boolean] Whether this property is required
+      def initialize(name:, from:, property: nil, map: nil, required: false)
+        @name = name
+        @from = from
+        @property = property
+        @map = map
+        @required = required
+      end
+
+      # Generate JSON schema definition for this reference property
+      #
+      # @return [Hash] The schema definition with a $ref pointer
+      def to_schema
+        {
+          name => {"$ref": from.to_ref(property:)}
+        }
+      end
+
+      # Generate validation schema for this reference property
+      #
+      # @param version [String, nil] The version to generate validation schema for
+      # @return [Hash] The validation schema for this reference
+      def to_validation_schema(version: nil)
+        {
+          name => from.to_validation_schema(version:, property: property)
+        }
+      end
+
+      # Create mapping for this reference property
+      # This delegates to the referenced schema's mapping with appropriate key prefixing
+      #
+      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String, nil] The version to create mapping for
+      # @return [Hash] The updated mapping hash
+      def mapping(key_prefix:, value_prefix:, mapping:, version:)
+        reference_mapping = from.mapping(version:, property:).dup
+        value_key_prefix = mapping_value_key(value_prefix:)
+
+        # Single field mapping
+        if property && reference_mapping.size == 1 && !reference_mapping.keys.first.include?(".")
+          reference_mapping = {
+            (key_prefix + [name]).join(".") => value_key_prefix
+          }
+        else
+          if value_key_prefix != "" && !value_key_prefix.end_with?(".")
+            value_key_prefix = "#{value_key_prefix}."
+          end
+
+          reference_mapping.transform_keys! { "#{(key_prefix + [name]).join(".")}.#{_1}" }
+          reference_mapping.transform_values! { "#{value_key_prefix}#{_1}" }
+        end
+
+        mapping.merge!(reference_mapping)
+      end
+
+      private
+
+      attr_reader :from, :property
+    end
+  end
+end

data/lib/verquest/properties.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Property types for defining versioned API request schemas
+  #
+  # The Properties module contains classes representing different types of
+  # properties that can be used when defining API request schemas. Each property
+  # type knows how to generate its own schema representation and handles mapping
+  # between external and internal parameter structures.
+  #
+  # @example Using properties in a schema definition
+  #   class UserRequest < Verquest::Base
+  #     version "2023-01" do
+  #       # Field - Basic scalar properties
+  #       field :email, type: :string, required: true
+  #
+  #       # Object - Nested structure with properties
+  #       object :address do
+  #         field :street, type: :string
+  #         field :city, type: :string, required: true
+  #       end
+  #
+  #       # Collection - Array of objects
+  #       collection :orders do
+  #         field :id, type: :string, required: true
+  #         field :amount, type: :number
+  #       end
+  #
+  #       # Array - Simple array of scalar values
+  #       array :tags, type: :string
+  #
+  #       # Reference - Reference to another schema
+  #       reference :payment, from: PaymentRequest
+  #     end
+  #   end
+  #
+  # @see Verquest::Properties::Base Base class for all property types
+  # @see Verquest::Properties::Field For scalar values like strings and numbers
+  # @see Verquest::Properties::Object For nested objects with their own properties
+  # @see Verquest::Properties::Collection For arrays of structured objects
+  # @see Verquest::Properties::Array For arrays of scalar values
+  # @see Verquest::Properties::Reference For references to other schemas
+  module Properties
+    # This module is a namespace for property type classes
+    # Each property type is defined in its own file under lib/verquest/properties/
+  end
+end

data/lib/verquest/result.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Verquest
+  # A result object for operation outcomes
+  #
+  # Result represents the outcome of an operation in the Verquest gem,
+  # particularly parameter mapping and validation operations. It follows
+  # the Result pattern, providing a consistent interface for both successful
+  # and failed operations, avoiding exceptions for control flow.
+  #
+  # @example Handling a successful result
+  #   result = Verquest::Result.success(transformed_params)
+  #   if result.success?
+  #     process_params(result.value)
+  #   end
+  #
+  # @example Handling a failed result
+  #   result = Verquest::Result.failure(["Invalid email format"])
+  #   if result.failure?
+  #     display_errors(result.errors)
+  #   end
+  class Result
+    # @!attribute [r] success
+    #   @return [Boolean] Whether the operation was successful
+    #
+    # @!attribute [r] value
+    #   @return [Object, nil] The result value if successful, nil otherwise
+    #
+    # @!attribute [r] errors
+    #   @return [Array] List of errors if failed, empty array otherwise
+    attr_reader :success, :value, :errors
+
+    # Initialize a new Result instance
+    #
+    # @param success [Boolean] Whether the operation was successful
+    # @param value [Object, nil] The result value for successful operations
+    # @param errors [Array, nil] List of errors for failed operations
+    # @return [Result] A new Result instance
+    def initialize(success:, value: nil, errors: nil)
+      @success = success
+      @value = value
+      @errors = errors
+    end
+
+    # Create a successful result with a value
+    #
+    # @param value [Object] The successful operation's result value
+    # @return [Result] A successful Result instance containing the value
+    def self.success(value)
+      new(success: true, value: value)
+    end
+
+    # Create a failed result with errors
+    #
+    # @param errors [Array, String] Error message(s) describing the failure
+    # @return [Result] A failed Result instance containing the errors
+    def self.failure(errors)
+      new(success: false, errors: errors)
+    end
+
+    # Check if the result represents a successful operation
+    #
+    # @return [Boolean] true if the operation was successful, false otherwise
+    def success?
+      success
+    end
+
+    # Check if the result represents a failed operation
+    #
+    # @return [Boolean] true if the operation failed, false otherwise
+    def failure?
+      !success
+    end
+  end
+end

data/lib/verquest/transformer.rb

@@ -0,0 +1,179 @@
+module Verquest
+  # Transforms parameters based on path mappings
+  #
+  # The Transformer class handles the conversion of parameter structures based on
+  # a mapping of source paths to target paths. It supports deep nested structures,
+  # array notations, and complex path expressions using dot notation.
+  #
+  # @example Basic transformation
+  #   mapping = {
+  #     "user.firstName" => "user.first_name",
+  #     "user.lastName" => "user.last_name",
+  #     "addresses[].zip" => "addresses[].postal_code"
+  #   }
+  #
+  #   transformer = Verquest::Transformer.new(mapping: mapping)
+  #   result = transformer.call({
+  #     user: {
+  #       firstName: "John",
+  #       lastName: "Doe"
+  #     },
+  #     addresses: [
+  #       { zip: "12345" },
+  #       { zip: "67890" }
+  #     ]
+  #   })
+  #
+  #   # Result will be:
+  #   # {
+  #   #   user: {
+  #   #     first_name: "John",
+  #   #     last_name: "Doe"
+  #   #   },
+  #   #   addresses: [
+  #   #     { postal_code: "12345" },
+  #   #     { postal_code: "67890" }
+  #   #   ]
+  #   # }
+  class Transformer
+    # Creates a new Transformer with the specified mapping
+    #
+    # @param mapping [Hash] A hash where keys are source paths and values are target paths
+    # @return [Transformer] A new transformer instance
+    def initialize(mapping:)
+      @mapping = mapping
+      @path_cache = {} # Cache for parsed paths to improve performance
+      precompile_paths # Prepare cache during initialization
+    end
+
+    # Transforms input parameters according to the provided mapping
+    #
+    # @param params [Hash] The input parameters to transform
+    # @return [Hash] The transformed parameters with symbol keys
+    def call(params)
+      result = {}
+
+      mapping.each do |source_path, target_path|
+        # Extract value using the source path
+        value = extract_value(params, parse_path(source_path.to_s))
+        next if value.nil?
+
+        # Set the extracted value at the target path
+        set_value(result, parse_path(target_path.to_s), value)
+      end
+
+      result
+    end
+
+    private
+
+    # @!attribute [r] mapping
+    #   @return [Hash] The source-to-target path mapping
+    # @!attribute [r] path_cache
+    #   @return [Hash] Cache for parsed paths
+    attr_reader :mapping, :path_cache
+
+    # Precompiles all paths from the mapping to improve performance
+    # This is called during initialization to prepare the cache
+    #
+    # @return [void]
+    def precompile_paths
+      mapping.each do |source_path, target_path|
+        parse_path(source_path.to_s)
+        parse_path(target_path.to_s)
+      end
+    end
+
+    # Parses a dot-notation path into structured path parts
+    # Uses memoization for performance optimization
+    #
+    # @param path [String] The dot-notation path (e.g., "user.address.street")
+    # @return [Array<Hash>] Array of path parts with :key and :array attributes
+    def parse_path(path)
+      path_cache[path] ||= path.split(".").map do |part|
+        if part.end_with?("[]")
+          {key: part[0...-2], array: true}
+        else
+          {key: part, array: false}
+        end
+      end
+    end
+
+    # Extracts a value from nested data structure using the parsed path parts
+    #
+    # @param data [Hash, Array, Object] The data to extract value from
+    # @param path_parts [Array<Hash>] The parsed path parts
+    # @return [Object, nil] The extracted value or nil if not found
+    def extract_value(data, path_parts)
+      return data if path_parts.empty?
+
+      current_part = path_parts.first
+      remaining_path = path_parts[1..]
+      key = current_part[:key]
+
+      case data
+      when Hash
+        # Check if the key exists (as string or symbol)
+        return nil unless data.key?(key.to_s) || data.key?(key.to_sym)
+
+        # Determine the actual key type used in the hash
+        actual_key = data.key?(key.to_s) ? key.to_s : key.to_sym
+        value = data[actual_key]
+
+        if current_part[:array] && value.is_a?(Array)
+          # Process array elements and filter out nil values
+          value.map { |item| extract_value(item, remaining_path) }.compact
+        else
+          # Continue traversing the path
+          extract_value(value, remaining_path)
+        end
+      when Array
+        if current_part[:array]
+          # Map through array elements with remaining path
+          data.map { |item| extract_value(item, remaining_path) }.compact
+        else
+          # Try to extract from each array element with the full path
+          result = data.map { |item| extract_value(item, path_parts) }.compact
+          result.empty? ? nil : result
+        end
+      else
+        # For scalar values, return only if we're at the end of the path
+        remaining_path.empty? ? data : nil
+      end
+    end
+
+    # Sets a value in a result hash at the specified path
+    #
+    # @param result [Hash] The result hash to modify
+    # @param path_parts [Array<Hash>] The parsed path parts
+    # @param value [Object] The value to set
+    # @return [Hash] The modified result hash with symbol keys
+    def set_value(result, path_parts, value)
+      return result if path_parts.empty?
+
+      current_part = path_parts.first
+      remaining_path = path_parts[1..]
+      key = current_part[:key].to_sym # Convert key to symbol for consistent symbol keys
+
+      if remaining_path.empty?
+        # End of path, set the value directly
+        result[key] = value
+      elsif current_part[:array] && value.is_a?(Array)
+        # Handle array notation in target path
+        result[key] ||= []
+
+        # Process each value in the array
+        value.each_with_index do |v, i|
+          result[key][i] ||= {}
+          set_value(result[key][i], remaining_path, v)
+        end
+      else
+        # Continue building nested structure
+        result[key] ||= {}
+        set_value(result[key], remaining_path, value)
+      end
+
+      result
+    end
+  end
+end