verquest 0.1.0 → 0.2.1

data/lib/verquest/version.rb

@@ -1,5 +1,212 @@
 # frozen_string_literal: true
 
 module Verquest
-  VERSION = "0.1.0"
+  # Represents a specific version of an API request schema
+  #
+  # The Version class manages the properties, schema generation, and mapping
+  # for a specific version of an API request. It holds the collection of
+  # properties that define the request structure and handles
+  # transforming between different property naming conventions.
+  #
+  # @example
+  #   version = Verquest::Version.new(name: "2023-01")
+  #   version.add(Verquest::Properties::Field.new(name: :email, type: :string))
+  #   version.prepare
+  #
+  #   # Generate schema
+  #   schema = version.schema
+  #
+  #   # Get mapping
+  #   mapping = version.mapping
+  class Version
+    # @!attribute [r] name
+    #   @return [String] The name/identifier of the version (e.g., "2023-01")
+    #
+    # @!attribute [r] properties
+    #   @return [Hash<Symbol, Verquest::Properties::Base>] The properties that define the version's schema
+    #
+    # @!attribute [r] schema
+    #   @return [Hash] The generated JSON schema for this version
+    #
+    # @!attribute [r] validation_schema
+    #   @return [Hash] The schema used for request validation
+    #
+    # @!attribute [r] mapping
+    #   @return [Hash] The mapping from schema property paths to internal paths
+    #
+    # @!attribute [r] transformer
+    #   @return [Verquest::Transformer] The transformer that applies the mapping
+    attr_reader :name, :properties, :schema, :validation_schema, :mapping, :transformer
+
+    # @!attribute [rw] schema_options
+    #   @return [Hash] Additional JSON schema options for this version
+    #
+    # @!attribute [rw] description
+    #   @return [String] Description of this version
+    attr_accessor :schema_options, :description
+
+    # Initialize a new Version instance
+    #
+    # @param name [String] The name/identifier of the version
+    # @return [Version] A new Version instance
+    def initialize(name:)
+      @name = name
+      @schema_options = {}
+      @properties = {}
+    end
+
+    # Add a property to this version
+    #
+    # @param property [Verquest::Properties::Base] The property to add
+    # @return [Verquest::Properties::Base] The added property
+    def add(property)
+      properties[property.name] = property
+    end
+
+    # Remove a property from this version by name
+    #
+    # @param property_name [Symbol, String] The name of the property to remove
+    # @return [Verquest::Properties::Base] The removed property
+    # @raise [PropertyNotFoundError] If the property doesn't exist
+    def remove(property_name)
+      properties.delete(property_name) || raise(PropertyNotFoundError.new("Property '#{property_name}' is not defined on '#{name}"))
+    end
+
+    # Check if this version has a property with the given name
+    #
+    # @param property_name [Symbol, String] The name of the property to check
+    # @return [Boolean] true if the property exists, false otherwise
+    def has?(property_name)
+      properties.key?(property_name)
+    end
+
+    # Copy properties from another version
+    #
+    # @param version [Verquest::Version] The version to copy properties from
+    # @param exclude_properties [Array<Symbol>] Names of properties to not copy
+    # @return [void]
+    # @raise [ArgumentError] If version is not a Verquest::Version instance
+    def copy_from(version, exclude_properties: [])
+      raise ArgumentError, "Expected a Verquest::Version instance" unless version.is_a?(Version)
+
+      version.properties.values.each do |property|
+        next if exclude_properties.include?(property.name)
+
+        add(property)
+      end
+    end
+
+    # Prepare this version by generating schema and creating transformer
+    #
+    # @return [void]
+    def prepare
+      return if frozen?
+
+      prepare_schema
+      prepare_validation_schema
+      prepare_mapping
+      @transformer = Transformer.new(mapping: mapping)
+
+      freeze
+    end
+
+    # Validate the schema against the metaschema
+    #
+    # @return [Boolean] true if the schema is valid, false otherwise
+    def validate_schema
+      schema_name = Verquest.configuration.json_schema_version
+
+      metaschema = JSON::Validator.validator_for_name(schema_name).metaschema
+      JSON::Validator.validate(metaschema, validation_schema)
+    end
+
+    # Validate request parameters against the version's validation schema
+    #
+    # @param params [Hash] The request parameters to validate
+    # @param component_reference [String] A reference string for components in the schema
+    # @param remove_extra_root_keys [Boolean] Whether to remove extra keys not in the schema
+    # @return [Array<Hash>] An array of validation error details, or empty if valid
+    def validate_params(params:, component_reference:, remove_extra_root_keys:)
+      schema_name = Verquest.configuration.json_schema_version
+
+      result = JSON::Validator.fully_validate(validation_schema, params, version: schema_name, errors_as_objects: true)
+      return result if result.empty?
+
+      result.map do |error|
+        schema = error.delete(:schema)
+        error[:message].gsub!(schema.to_s, component_reference)
+      end
+    end
+
+    # Get the mapping for a specific property
+    #
+    # @param property [Symbol, String] The property name to get the mapping for
+    # @return [Hash] The mapping for the property
+    # @raise [PropertyNotFoundError] If the property doesn't exist
+    def mapping_for(property)
+      raise PropertyNotFoundError.new("Property '#{property}' is not defined on '#{name}'") unless has?(property)
+
+      {}.tap do |mapping|
+        properties[property].mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
+      end
+    end
+
+    # Map request parameters to internal representation using the transformer
+    #
+    # @param params [Hash] The request parameters to map
+    # @return [Hash] The mapped parameters
+    def map_params(params)
+      transformer.call(params)
+    end
+
+    private
+
+    # Generates the JSON schema for this version
+    #
+    # Creates a schema object with type, description, required properties,
+    # and property definitions based on the properties in this version.
+    # The schema is frozen to prevent modification after preparation.
+    #
+    # @return [Hash] The frozen schema hash
+    def prepare_schema
+      @schema = {
+        type: :object,
+        description: description,
+        required: properties.values.select(&:required).map(&:name),
+        properties: properties.transform_values { |property| property.to_schema[property.name] }
+      }.merge(schema_options).freeze
+    end
+
+    # Generates the validation schema for this version
+    #
+    # Similar to prepare_schema but specifically for validation purposes.
+    # The validation schema will include all referenced components and properties.
+    #
+    # @return [Hash] The frozen validation schema hash
+    def prepare_validation_schema
+      @validation_schema = {
+        type: :object,
+        description: description,
+        required: properties.values.select(&:required).map(&:name),
+        properties: properties.transform_values { |property| property.to_validation_schema(version: name)[property.name] }
+      }.merge(schema_options).freeze
+    end
+
+    # Prepares the parameter mapping for this version
+    #
+    # Collects mappings from all properties in this version and checks for
+    # duplicate mappings, which would cause conflicts during transformation.
+    #
+    # @return [Hash] The mapping from schema property paths to internal paths
+    # @raise [MappingError] If duplicate mappings are detected
+    def prepare_mapping
+      @mapping = properties.values.each_with_object({}) do |property, mapping|
+        property.mapping(key_prefix: [], value_prefix: [], mapping: mapping, version: name)
+      end
+
+      if (duplicates = mapping.keys.select { |k| mapping.values.count(k) > 1 }).any?
+        raise MappingError.new("Mapping must be unique. Found duplicates in version '#{name}': #{duplicates.join(", ")}")
+      end
+    end
+  end
 end

data/lib/verquest/version_resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Resolves requested version identifiers to actual version objects
+  #
+  # The VersionResolver handles version resolution logic, finding the appropriate
+  # version to use based on a requested version identifier. It implements a "downgrading"
+  # strategy - when an exact version match isn't found, it returns the closest earlier version.
+  #
+  # @example Resolving a version
+  #   versions = ["2025-01", "2025-06", "2026-01"]
+  #
+  #   # Exact match
+  #   Verquest::VersionResolver.call("2025-06", versions) # => "2025-06"
+  #
+  #   # Between versions - returns previous version
+  #   Verquest::VersionResolver.call("2025-04", versions) # => "2025-01"
+  #
+  #   # After latest version - returns latest
+  #   Verquest::VersionResolver.call("2026-06", versions) # => "2026-01"
+  class VersionResolver
+    # Resolves a requested version to the appropriate available version
+    #
+    # This method implements the version resolution strategy:
+    # - If an exact match is found, that version is returned
+    # - If the requested version is between two available versions, the earlier one is returned
+    # - If the requested version is after all available versions, the latest version is returned
+    #
+    # @param requested_version [String] The version identifier requested
+    # @param versions [Array<String>] List of available version identifiers, sorted by age (oldest first)
+    # @return [String, nil] The resolved version, or nil if no versions available
+    def self.call(requested_version, versions)
+      versions.each_with_index do |version, index|
+        return version if version == requested_version
+
+        if requested_version > version && ((versions[index + 1] && requested_version < versions[index + 1]) || !versions[index + 1])
+          return version
+        end
+      end
+    end
+  end
+end

data/lib/verquest/versions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Container for managing multiple API versions
+  #
+  # The Versions class stores and provides access to all available versions of an
+  # API request schema. It handles adding new versions and resolving version identifiers
+  # to specific Version objects based on the configured version resolution strategy.
+  #
+  # @example Adding and resolving versions
+  #   versions = Verquest::Versions.new
+  #
+  #   # Add versions
+  #   versions.add(Verquest::Version.new(name: "2022-01"))
+  #   versions.add(Verquest::Version.new(name: "2023-01"))
+  #
+  #   # Resolve a version
+  #   version = versions.resolve("2022-06") # Returns "2022-01" version based on resolver
+  class Versions
+    # @!attribute [rw] description
+    #   @return [String] Default description for versions that don't specify one
+    #
+    # @!attribute [rw] schema_options
+    #   @return [Hash] Default schema options for versions that don't specify any
+    attr_accessor :description, :schema_options
+
+    # Initialize a new Versions container
+    #
+    # @return [Versions] A new Versions instance
+    def initialize
+      @versions = {}
+      @schema_options = {}
+    end
+
+    # Add a version to the container
+    #
+    # @param version [Verquest::Version] The version to add
+    # @return [Verquest::Version] The added version
+    # @raise [ArgumentError] If the provided object is not a Version instance
+    def add(version)
+      raise ArgumentError, "Expected a Verquest::Version instance" unless version.is_a?(Verquest::Version)
+
+      versions[version.name] = version
+    end
+
+    # Resolve a version identifier to a specific Version object
+    #
+    # Uses the configured version resolver to determine which version to use
+    # based on the requested version identifier.
+    #
+    # @param version_name [String] The version identifier to resolve
+    # @return [Verquest::Version] The resolved Version object
+    def resolve(version_name)
+      resolved_version_name = Verquest.configuration.version_resolver.call(version_name, versions.keys.sort)
+
+      versions[resolved_version_name] || raise(Verquest::VersionNotFoundError, "Version '#{version_name}' not found")
+    end
+
+    private
+
+    # @!attribute [r] versions
+    #   @return [Hash<String, Verquest::Version>] The versions stored in this container
+    attr_reader :versions
+  end
+end

data/lib/verquest.rb

@@ -1,10 +1,103 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
+require "json-schema"
+
+loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
+loader.push_dir(File.dirname(__FILE__))
 loader.setup
 
+# Verquest is a Ruby gem for versioning API requests
+#
+# Verquest allows you to define and manage versioned API request schemas,
+# handle parameter mapping between different versions, validate incoming
+# parameters against schemas, and generate documentation.
+#
+# @example Basic usage
+#   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
+#
+#   # Map and validate parameters for a specific version
+#   result = UserCreateRequest.map(params, version: "2025-07", validate: true)
+#
+#   if result.success?
+#     process_user(result.value)
+#   else
+#     handle_errors(result.errors)
+#   end
+#
+# @see Verquest::Base Base class for creating versioned request schemas
+# @see Verquest::Configuration Configuration options for Verquest
 module Verquest
-  class Error < StandardError; end
-  # Your code goes here...
+  # Base error class for all Verquest-related errors
+  # @api public
+  Error = Class.new(StandardError)
+
+  # Error raised when a requested version cannot be found
+  # @api public
+  VersionNotFoundError = Class.new(Verquest::Error)
+
+  # Error raised when a requested property cannot be found in a version
+  # @api public
+  PropertyNotFoundError = Class.new(Verquest::Error)
+
+  # Error raised when there are issues with property mappings
+  # @api public
+  MappingError = Class.new(Verquest::Error)
+
+  # Error raised when parameters do not match the expected schema
+  # @api public
+  InvalidParamsError = Class.new(Verquest::Error) do
+    attr_reader :errors
+
+    # @param message [String] error message
+    # @param errors [Array] validation errors
+    def initialize(message, errors:)
+      super(message)
+      @errors = errors
+    end
+  end
+
+  class << self
+    # Returns the global configuration for Verquest
+    #
+    # @return [Verquest::Configuration] The configuration instance
+    # @see Verquest::Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure Verquest with the given block
+    #
+    # @example
+    #   Verquest.configure do |config|
+    #     config.validate_params = true
+    #     config.current_version = -> { "2023-06" }
+    #   end
+    #
+    # @yield [configuration] The configuration instance
+    # @yieldparam configuration [Verquest::Configuration] The configuration to modify
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+  end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verquest
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Petr Hlavicka
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -23,23 +24,56 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-description: Verquest is a Ruby gem that helps you version your public API requests,
-  making it easier to manage changes and maintain backward compatibility with OpenAPI
-  support.
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Verquest helps you version API requests, simplifying the management of
+  changes, handling the mapping for internal versus external names and structures,
+  validating parameters, and exporting your requests to JSON Schema components for
+  OpenAPI.
 email:
-- petr@hlavicka.cz
+- yes@petr.codes
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/verquest.rb
+- lib/verquest/base.rb
+- lib/verquest/base/helper_class_methods.rb
+- lib/verquest/base/private_class_methods.rb
+- lib/verquest/base/public_class_methods.rb
+- lib/verquest/configuration.rb
+- lib/verquest/gem_version.rb
+- lib/verquest/properties.rb
+- lib/verquest/properties/array.rb
+- lib/verquest/properties/base.rb
+- lib/verquest/properties/collection.rb
+- lib/verquest/properties/field.rb
+- lib/verquest/properties/object.rb
+- lib/verquest/properties/reference.rb
+- lib/verquest/result.rb
+- lib/verquest/transformer.rb
 - lib/verquest/version.rb
+- lib/verquest/version_resolver.rb
+- lib/verquest/versions.rb
 homepage: https://github.com/CiTroNaK/verquest
 licenses:
 - MIT
@@ -47,6 +81,7 @@ metadata:
   homepage_uri: https://github.com/CiTroNaK/verquest
   source_code_uri: https://github.com/CiTroNaK/verquest
   changelog_uri: https://github.com/CiTroNaK/verquest/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -54,14 +89,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
-summary: Version your public API requests with ease
+summary: Verquest is a Ruby gem that offers an elegant solution for versioning API
+  requests
 test_files: []