verquest 0.1.0 → 0.2.0

data/lib/verquest/base/private_class_methods.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Private class methods for Verquest::Base
+  #
+  # This module contains internal class methods used by the versioning system
+  # that are not intended for direct use by client code.
+  #
+  # @api private
+  module Base::PrivateClassMethods
+    # Resolves the version to use, either from the provided version,
+    # configuration's current_version, or raises an error if none is available
+    #
+    # @param version [String, nil] The specific version to resolve
+    # @return [Verquest::Version] The resolved version object
+    # @raise [ArgumentError] If no version is provided and no current_version is configured
+    def resolve(version)
+      if version.nil? && Verquest.configuration.current_version
+        version = instance_exec(&Verquest.configuration.current_version)
+      elsif version.nil?
+        raise ArgumentError, "Version must be provided or set by Verquest.configuration.current_version"
+      end
+
+      versions.resolve(version)
+    end
+
+    private
+
+    # @return [Verquest::Version, Verquest::Properties::Object] The current scope being defined
+    attr_reader :current_scope
+
+    # @return [Hash] Default options for property definitions
+    # Default options used when using teh with_options method.
+    attr_reader :default_options
+
+    # Returns the versions container, initializing it if needed
+    #
+    # @return [Verquest::Versions] The versions container
+    def versions
+      @versions ||= Versions.new
+    end
+
+    # Defines a new version with optional inheritance from another version
+    #
+    # @param name [String] The name/identifier of the version
+    # @param inherit [Boolean, String] Whether to inherit from current scope or specific version name
+    # @param exclude_properties [Array<Symbol>] Properties to exclude when inheriting
+    # @yield Block defining the version's structure and properties
+    # @return [void]
+    def version(name, inherit: true, exclude_properties: [], &block)
+      version = Version.new(name:)
+      versions.add(version)
+
+      if inherit && @current_scope
+        version.copy_from(@current_scope, exclude_properties:)
+      elsif inherit.is_a?(String)
+        inherit_version = versions.resolve(inherit)
+        version.copy_from(inherit_version, exclude_properties:)
+      end
+
+      @default_options = {}
+      @current_scope = version
+
+      instance_exec(&block)
+    ensure
+      version.description ||= versions.description
+      version.schema_options = versions.schema_options.merge(version.schema_options)
+      version.prepare
+    end
+
+    # Sets the description for the current version scope or globally
+    #
+    # @param text [String] The description text
+    # @return [void]
+    # @raise [RuntimeError] If called outside of a version scope
+    def description(text)
+      if current_scope.nil?
+        versions.description = text
+      elsif current_scope.is_a?(Version)
+        current_scope.description = text
+      else
+        raise "Description can only be set within a version scope or globally"
+      end
+    end
+
+    # Sets additional schema options for the current version scope or globally
+    #
+    # @param schema_options [Hash] The schema options to set
+    # @return [void]
+    # @raise [RuntimeError] If called outside of a version scope
+    def schema_options(**schema_options)
+      camelize(schema_options)
+
+      if current_scope.nil?
+        versions.schema_options = schema_options
+      elsif current_scope.is_a?(Version)
+        current_scope.schema_options = schema_options
+      else
+        raise "Additional properties can only be set within a version scope or globally"
+      end
+    end
+
+    # Executes the given block with the specified options, temporarily overriding
+    # the default options for the duration of the block
+    #
+    # @param options [Hash] The options to set during the block execution
+    # @yield Block to be executed with the temporary options
+    # @return [void]
+    def with_options(**options, &block)
+      camelize(options)
+
+      original_options = default_options
+      @default_options = options.except(:map)
+
+      instance_exec(&block)
+    ensure
+      @default_options = original_options
+    end
+
+    # Defines a new field for the current version scope
+    #
+    # @param name [Symbol] The name of the field
+    # @param type [Symbol] The data type of the field
+    # @param map [String, nil] An optional mapping to another field
+    # @param required [Boolean] Whether the field is required
+    # @param schema_options [Hash] Additional schema options for the field
+    # @return [void]
+    def field(name, type: nil, map: nil, required: false, **schema_options)
+      camelize(schema_options)
+
+      type = default_options.fetch(:type, type)
+      required = default_options.fetch(:required, required)
+      schema_options = default_options.except(:type, :required).merge(schema_options)
+
+      field = Properties::Field.new(name:, type:, map:, required:, **schema_options)
+      current_scope.add(field)
+    end
+
+    # Defines a new object for the current version scope
+    #
+    # @param name [Symbol] The name of the object
+    # @param map [String, nil] An optional mapping to another object
+    # @param required [Boolean] Whether the object is required
+    # @param schema_options [Hash] Additional schema options for the object
+    # @yield Block executed in the context of the new object definition
+    # @return [void]
+    def object(name, map: nil, required: false, **schema_options, &block)
+      unless block_given?
+        raise ArgumentError, "a block must be given to define the object"
+      end
+
+      camelize(schema_options)
+      required = default_options.fetch(:required, required)
+      schema_options = default_options.except(:type, :required).merge(schema_options)
+
+      object = Properties::Object.new(name:, map:, required:, **schema_options)
+      current_scope.add(object)
+
+      if block_given?
+        previous_scope = current_scope
+        @current_scope = object
+
+        instance_exec(&block)
+      end
+    ensure
+      @current_scope = previous_scope if block_given?
+    end
+
+    # Defines a new collection for the current version scope
+    #
+    # @param name [Symbol] The name of the collection
+    # @param item [Class, nil] The item type in the collection
+    # @param required [Boolean] Whether the collection is required
+    # @param map [String, nil] An optional mapping to another collection
+    # @param schema_options [Hash] Additional schema options for the collection
+    # @yield Block executed in the context of the new collection definition
+    # @return [void]
+    def collection(name, item: nil, required: false, map: nil, **schema_options, &block)
+      if item.nil? && !block_given?
+        raise ArgumentError, "item must be provided or a block must be given to define the collection"
+      elsif !item.nil? && !block_given? && !(item <= Verquest::Base)
+        raise ArgumentError, "item must be a child of Verquest::Base class or nil" unless type.is_a?(Verquest::Properties::Base)
+      end
+
+      camelize(schema_options)
+      required = default_options.fetch(:required, required)
+      schema_options = default_options.except(:required).merge(schema_options)
+
+      collection = Properties::Collection.new(name:, item:, required:, map:, **schema_options)
+      current_scope.add(collection)
+
+      if block_given?
+        previous_scope = current_scope
+        @current_scope = collection
+
+        instance_exec(&block)
+      end
+    ensure
+      @current_scope = previous_scope if block_given?
+    end
+
+    # Defines a new reference for the current version scope
+    #
+    # @param name [Symbol] The name of the reference
+    # @param from [Verquest::Base] The source of the reference
+    # @param property [Symbol, nil] An optional specific property to reference
+    # @param map [String, nil] An optional mapping to another reference
+    # @param required [Boolean] Whether the reference is required
+    # @return [void]
+    def reference(name, from:, property: nil, map: nil, required: false)
+      required = default_options.fetch(:required, required)
+
+      reference = Properties::Reference.new(name:, from:, property:, map:, required:)
+      current_scope.add(reference)
+    end
+
+    # Defines a new array property for the current version scope
+    #
+    # @param name [Symbol] The name of the array property
+    # @param type [String] The data type of the array elements
+    # @param required [Boolean] Whether the array property is required
+    # @param map [String, nil] An optional mapping to another array property
+    # @param schema_options [Hash] Additional schema options for the array property
+    # @return [void]
+    def array(name, type:, required: false, map: nil, **schema_options)
+      camelize(schema_options)
+
+      type = default_options.fetch(:type, type)
+      required = default_options.fetch(:required, required)
+      schema_options = default_options.except(:type, :required).merge(schema_options)
+
+      array = Properties::Array.new(name:, type:, required:, map:, **schema_options)
+      current_scope.add(array)
+    end
+
+    # Excludes specified properties from the current scope by removing them
+    # from the version's property set
+    #
+    # @param names [Array<Symbol>] The names of the properties to exclude
+    # @return [void]
+    def exclude_properties(*names)
+      names.each do |name|
+        current_scope.remove(name)
+      end
+    end
+  end
+end

data/lib/verquest/base/public_class_methods.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Public class methods to be included in Verquest::Base
+  #
+  # This module contains class methods that handle parameter mapping, schema generation,
+  # and validation functionality for Verquest API request objects.
+  module Base::PublicClassMethods
+    # Maps incoming parameters to the appropriate structure based on version mapping
+    #
+    # @param params [Hash] The parameters to be mapped
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @param validate [Boolean, nil] Whether to validate the params, defaults to configuration setting
+    # @param remove_extra_root_keys [Boolean, nil] Whether to remove extra keys at the root level, defaults to configuration setting
+    # @return [Verquest::Result] Success result with mapped params or failure result with validation errors
+    def process(params, version: nil, validate: nil, remove_extra_root_keys: nil)
+      validate = Verquest.configuration.validate_params if validate.nil?
+      remove_extra_root_keys = Verquest.configuration.remove_extra_root_keys if remove_extra_root_keys.nil?
+
+      version_class = resolve(version)
+
+      params = params.dup
+      params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
+      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys
+
+      if validate && (validation_result = version_class.validate_params(params: params, component_reference: to_ref, remove_extra_root_keys: remove_extra_root_keys)) && validation_result.any?
+        case Verquest.configuration.validation_error_handling
+        when :raise
+          raise InvalidParamsError.new("Validation failed", errors: validation_result)
+        when :result
+          Result.failure(validation_result)
+        end
+      else
+        mapped_params = version_class.map_params(params)
+
+        case Verquest.configuration.validation_error_handling
+        when :raise
+          mapped_params
+        when :result
+          Result.success(mapped_params)
+        end
+      end
+    end
+
+    # Returns the JSON schema for the request
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @return [Hash] The JSON schema for the request
+    def to_schema(version: nil)
+      resolve(version).schema
+    end
+
+    # Returns the validation JSON schema for the request or a specific property. It contains all schemas from references.
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @param property [Symbol, nil] Specific property to retrieve schema for
+    # @return [Hash] The validation schema or property schema
+    def to_validation_schema(version: nil, property: nil)
+      version = resolve(version)
+
+      if property
+        version.validation_schema[:properties][property]
+      else
+        version.validation_schema
+      end
+    end
+
+    # Validates the generated JSON schema structure
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @return [Boolean] True if schema is valid
+    def validate_schema(version: nil)
+      resolve(version).validate_schema
+    end
+
+    # Returns the mapping for a specific version or property
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @param property [Symbol, nil] Specific property to retrieve mapping for
+    # @return [Hash] The mapping configuration
+    def mapping(version: nil, property: nil)
+      version = resolve(version)
+
+      if property
+        version.mapping_for(property)
+      else
+        version.mapping
+      end
+    end
+
+    # Returns the JSON reference for the request or a specific property
+    #
+    # @param property [Symbol, nil] Specific property to retrieve reference for
+    # @return [String] The JSON reference for the request or property
+    def to_ref(property: nil)
+      base = "#/components/schemas/#{component_name}"
+
+      property ? "#{base}/properties/#{property}" : base
+    end
+
+    # Returns the component name derived from the class name. It is used in JSON schema references.
+    #
+    # @return [String] The component name
+    def component_name
+      name.to_s.split("::", 2).last.tr("::", "")
+    end
+  end
+end

data/lib/verquest/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Base class for API request definition and mapping
+  #
+  # This class is the foundation of the Verquest versioning system. Classes that inherit from Base
+  # can define their request structure using the versioning DSL, including fields, objects,
+  # collections, and references. The Base class handles parameter mapping, schema generation,
+  # and validation based on version specifications.
+  #
+  # @example Define a versioned API request class
+  #   class UserCreateRequest < Verquest::Base
+  #     description "User Create Request"
+  #     schema_options additional_properties: false
+  #
+  #     version "2025-06" do
+  #       field :email, type: :string, required: true, format: "email"
+  #       field :name, type: :string
+  #
+  #       object :address do
+  #         field :street, type: :string, map: "/address_street"
+  #         field :city, type: :string, required: true, map: "/address_city"
+  #         field :zip_code, type: :string, map: "/address_zip_code"
+  #       end
+  #     end
+  #
+  #     version "2025-08", exclude_properties: %i[name] do
+  #       field :name, type: :string, required: true
+  #     end
+  #   end
+  #
+  # @see Verquest::Base::PublicClassMethods for available class methods
+  class Base
+    extend Base::HelperClassMethods
+    extend Base::PrivateClassMethods
+    extend Base::PublicClassMethods
+  end
+end

data/lib/verquest/configuration.rb

@@ -0,0 +1,73 @@
+module Verquest
+  # Configuration for the Verquest gem
+  #
+  # This class manages configuration settings for the Verquest gem, including
+  # validation behavior, JSON Schema version, and version resolution strategy.
+  # It's used to customize the behavior of versioned API requests.
+  #
+  # @example Basic configuration
+  #   Verquest.configure do |config|
+  #     config.validate_params = true
+  #     config.current_version = -> { Current.api_version }
+  #   end
+  class Configuration
+    # @!attribute [rw] validate_params
+    #   Controls whether parameters are automatically validated against the schema
+    #   @return [Boolean] true if validation is enabled, false otherwise
+    #
+    # @!attribute [rw] json_schema_version
+    #   The JSON Schema draft version to use for validation and schema generation (see the json-schema gem)
+    #   @return [Symbol] The JSON Schema version (e.g., :draft4, :draft5)
+    #
+    # @!attribute [rw] validation_error_handling
+    #   Controls how errors during parameter processing are handled
+    #   @return [Symbol] :raise to raise errors (default) or :result to return errors in the Result object
+    #
+    # @!attribute [rw] remove_extra_root_keys
+    #   Controls if extra root keys not defined in the schema should be removed from the parameters
+    #   @return [Boolean] true if extra keys should be removed, false otherwise
+    attr_accessor :validate_params, :json_schema_version, :validation_error_handling, :remove_extra_root_keys
+
+    # @!attribute [r] current_version
+    #   A callable object that returns the current API version to use when not explicitly specified
+    #   @return [#call] An object responding to call that determines the current version
+    #
+    # @!attribute [r] version_resolver
+    #   The resolver used to map version strings/identifiers to version objects
+    #   @return [#call] An object that responds to `call` for resolving versions
+    attr_reader :current_version, :version_resolver
+
+    # Initialize a new Configuration with default values
+    #
+    # @return [Configuration] A new configuration instance with default settings
+    def initialize
+      @validate_params = true
+      @json_schema_version = :draft6
+      @validation_error_handling = :raise # or :result
+      @remove_extra_root_keys = true
+      @version_resolver = VersionResolver
+    end
+
+    # Sets the current version strategy using a callable object
+    #
+    # @param current_version [#call] An object that returns the current version when called
+    # @raise [ArgumentError] If the provided value doesn't respond to call
+    # @return [#call] The callable object that was set
+    def current_version=(current_version)
+      raise ArgumentError, "The current_version must respond to a call method" unless current_version.respond_to?(:call)
+
+      @current_version = current_version
+    end
+
+    # Sets the version resolver
+    #
+    # @param version_resolver [#call] An object with a call method for resolving versions
+    # @raise [ArgumentError] If the provided resolver doesn't respond to call
+    # @return [#call] The resolver that was set
+    def version_resolver=(version_resolver)
+      raise ArgumentError, "The version_resolver must respond to a call method" unless version_resolver.respond_to?(:call)
+
+      @version_resolver = version_resolver
+    end
+  end
+end

data/lib/verquest/gem_version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Verquest
+  GEM_VERSION = "0.2.0"
+end

data/lib/verquest/properties/array.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Array property type for schema generation and mapping
+    #
+    # Represents an array data structure in the schema with specified item type.
+    # Used to define arrays of scalar types (string, number, integer, boolean).
+    #
+    # @example Define an array of strings
+    #   array = Verquest::Properties::Array.new(
+    #     name: :tags,
+    #     type: :string,
+    #     required: true
+    #   )
+    class Array < Base
+      # Initialize a new Array property
+      #
+      # @param name [Symbol] The name of the property
+      # @param type [Symbol] The type of items in the array
+      # @param map [String, nil] The mapping path for this property (nil for no explicit mapping)
+      # @param required [Boolean] Whether this property is required
+      # @param schema_options [Hash] Additional JSON schema options for this property
+      # @raise [ArgumentError] If attempting to map an array to the root
+      def initialize(name:, type:, map: nil, required: false, **schema_options)
+        raise ArgumentError, "You can not map array to the root" if map == "/"
+
+        @name = name
+        @type = type
+        @map = map
+        @required = required
+        @schema_options = schema_options
+      end
+
+      # Generate JSON schema definition for this array property
+      #
+      # @return [Hash] The schema definition for this array property
+      def to_schema
+        {
+          name => {
+            type: :array,
+            items: {type: type}
+          }.merge(schema_options)
+        }
+      end
+
+      # Create mapping for this array property
+      #
+      # @param key_prefix [Array<Symbol>] Prefix for the source key
+      # @param value_prefix [Array<Symbol>] Prefix for the target value
+      # @param mapping [Hash] The mapping hash to be updated
+      # @param version [String, nil] The version to create mapping for, defaults to configuration setting
+      # @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/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Verquest
+  module Properties
+    # Base class for all property types
+    #
+    # This abstract class defines the interface for all property types
+    # in the Verquest schema system. All property classes should inherit
+    # from this base class and implement its required methods.
+    #
+    # @abstract Subclass and override {#to_schema}, {#mapping} to implement
+    class Base
+      # @!attribute [rw] name
+      #   @return [Symbol] The name of the property
+      # @!attribute [rw] required
+      #   @return [Boolean] Whether this property is required
+      # @!attribute [rw] map
+      #   @return [String, nil] The mapping path for this property
+      attr_accessor :name, :required, :map
+
+      # Adds a child property to this property
+      # @abstract
+      # @param property [Verquest::Properties::Base] The property to add
+      # @raise [NoMethodError] This is an abstract method that must be overridden
+      def add(property)
+        raise NoMethodError
+      end
+
+      # Generates JSON schema for this property
+      # @abstract
+      # @return [Hash] The schema definition for this property
+      # @raise [NoMethodError] This is an abstract method that must be overridden
+      def to_schema
+        raise NoMethodError
+      end
+
+      # Generates validation schema for this property, defaults to the same as `to_schema`
+      # @param version [String, nil] The version to generate validation schema for
+      # @return [Hash] The validation schema for this property
+      def to_validation_schema(version: nil)
+        to_schema
+      end
+
+      # Creates mapping for this property
+      # @abstract
+      # @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
+      # @raise [NoMethodError] This is an abstract method that must be overridden
+      def mapping(key_prefix:, value_prefix:, mapping:, version:)
+        raise NoMethodError
+      end
+
+      private
+
+      # Determines the mapping target key based on mapping configuration
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param collection [Boolean] Whether this is a collection mapping
+      # @return [String] The target mapping key
+      def mapping_value_key(value_prefix:, collection: false)
+        value_key = if map.nil?
+          (value_prefix + [name]).join(".")
+        elsif map == "/"
+          ""
+        elsif map.start_with?("/")
+          map.gsub(%r{^/}, "")
+        else
+          (value_prefix + map.split(".")).join(".")
+        end
+
+        if collection
+          value_key + "[]"
+        else
+          value_key
+        end
+      end
+
+      # Determines the mapping target value prefix based on mapping configuration
+      # @param value_prefix [Array<String>] Prefix for the target value
+      # @param collection [Boolean] Whether this is a collection mapping
+      # @return [Array<String>] The target mapping value prefix
+      def mapping_value_prefix(value_prefix:, collection: false)
+        value_prefix = if map.nil?
+          value_prefix + [name]
+        elsif map == "/"
+          []
+        elsif map.start_with?("/")
+          map.gsub(%r{^/}, "").split(".")
+        else
+          value_prefix + map.split(".")
+        end
+
+        if collection && value_prefix.any?
+          last = value_prefix.pop
+          value_prefix.push((last.to_s + "[]").to_sym)
+        end
+
+        value_prefix
+      end
+    end
+  end
+end