verquest 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e8b4a4b772142287128e69acb19493af2b5976bc9067b7fe5fc00aae46132c
-  data.tar.gz: 6f940f2835e31cabc89c5a8b6ab8d7c58bc13a4bf9a12bdf006b8c51125f5a2e
+  metadata.gz: 602d7b11dee9986d5005901641dc12ef407b61ee172f6c60972e16bff2bcae6b
+  data.tar.gz: 021af67a6befd09f2375683c2641696694690fceee4954eec9c71adce48bb78f
 SHA512:
-  metadata.gz: 978761b91ed5208803b703a939d5f63b93317f121099b65c4ef7e4cce0bd7301ba23844037269448d6252ee1ab1ac4fc20d448360cea3a23c074f76786092676
-  data.tar.gz: bde0a68b63950fc4aed639556a03f2cec9b011adea2ae39fef76c4e9f3ff1226176480ad146a6a0a64da5e9f64c98fc337b13368364321e402363d8658ca2b12
+  metadata.gz: d39fc339be03bac745e9e0e353136d25940de8cca6bfe8a28224bfa64fd05db984bc957473b404fcc68b40c1d1ec62c010238b374ec204eaad7fc1d434d5ca85
+  data.tar.gz: 24292a5eb4c594b1f58e724987c9acc2427347152f037027c234d0f0fbff0945afaaf2aa5369e322b022ab8e61ad92302a73397dccbbeb44f24a67eb8f1e28ca

data/.yardopts

@@ -0,0 +1,8 @@
+--private
+--title "Verquest Documentation"
+--exclude lib/verquest/gem_version.rb
+lib/**/*.rb
+-
+LICENSE.txt
+CHANGELOG.md
+CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+- Initial support for versions, fields, collections, and references.
+
 ## [0.1.0] - 2025-06-14
 
 - Initial release

data/README.md

@@ -1,38 +1,441 @@
 # Verquest
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/verquest.svg)](https://badge.fury.io/rb/verquest)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/verquest`. To experiment with that code, run `bin/console` for an interactive prompt.
+Verquest is a Ruby gem that offers an elegant solution for versioning API requests. It simplifies the process of defining and evolving your API schema over time, with robust support for:
+
+- Defining versioned request structures
+- Gracefully handling API versioning
+- Mapping between external and internal parameter structures
+- Validating parameters against [JSON Schema](https://json-schema.org/learn)
+- Generating components for OpenAPI documentation
+- Mapping error keys back to the external API structure (planned feature)
+
+> The gem is still in development. Until version 1.0, the API may change. There are some features like `oneOf`, `anyOf`, `allOf` that are not implemented yet.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem "verquest", "~> 0.2"
+```
+
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Quick Start
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+### Define a versioned API requests
+
+Address Create Request
+```ruby
+class AddressCreateRequest < Verquest::Base
+  description "Address Create Request"
+  schema_options additional_properties: false
+
+  version "2025-06" do # or v1 or anything you need (use a custom version_resolver if needed)
+    with_options type: :string, required: true do
+      field :street, description: "Street address"
+      field :city, description: "City of residence"
+      field :postal_code, description: "Postal code"
+      field :country, description: "Country of residence"
+    end
+  end
+end
+````
+
+User Create Request that uses the `AddressCreateRequest`
+```ruby
+class UserCreateRequest < Verquest::Base
+  description "User Create Request"
+  schema_options additional_properties: false
+
+  version "2025-06" do # or v1 or anything you need (use a custom version_resolver if needed)
+    with_options type: :string, required: true do
+      field :first_name, description: "The first name of the user", max_length: 50
+      field :last_name, description: "The last name of the user", max_length: 50
+      field :email, format: "email", description: "The email address of the user"
+    end
+    
+    field :birth_date, type: :string, format: "date", description: "The birth date of the user"
+
+    reference :address, from: AddressCreateRequest, required: true
+
+    collection :permissions, description: "Permissions associated with the user" do
+      field :name, type: :string, required: true, description: "Name of the permission"
+      
+      with_options type: :boolean do
+        field :read, description: "Permission to read"
+        field :write, description: "Permission to write"
+      end
+    end
+    
+    field :role, type: :string, description: "Role of the user", enum: %w[member manager], default: "member"
+    
+    object :profile_details do
+      field :bio, type: :string, description: "Short biography of the user"
+      
+      array :hobbies, type: :string, description: "Tags associated with the user"
+      
+      object :social_links, description: "Some social networks" do
+        with_options type: :string, format: "uri" do
+          field :github, description: "GitHub profile URL"
+          field :mastodon, description: "Mastodon profile URL"
+        end
+      end
+    end
+  end
+end
+```
+
+### Example usage in Rails Controller
+
+```ruby
+
+class UsersController < ApplicationController
+  rescue_from Verquest::InvalidParamsError, with: :handle_invalid_params
+  
+  def create
+    result = Users::Create.call(params: user_params) # service object to handle the creation logic
+
+    if result.success?
+      # render success response
+    else
+      # render error response
+    end
+  end
+
+  private
+
+  def user_params
+    UserCreateRequest.process(params, version: params[:api_version])
+  end
+end
+```
+
+### JSON schema for OpenAPI
+You can generate JSON Schema for your versioned requests, which can be used for API documentation:
+
+```ruby
+UserCreateRequest.to_schema(version: "2025-06")
+```
+
+Output:
+```ruby
+{
+  type: :object,
+  description: "User Create Request",
+  required: [:first_name, :last_name, :email, :address],
+  properties: {
+    first_name: {type: :string, description: "The first name of the user", maxLength: 50},
+    last_name: {type: :string, description: "The last name of the user", maxLength: 50},
+    email: {type: :string, format: "email", description: "The email address of the user"},
+    birth_date: {type: :string, format: "date", description: "The birth date of the user"},
+    address: {"$ref": "#/components/schemas/AddressCreateRequest"},
+    permissions: {
+      type: :array, 
+      items: {
+        type: :object, 
+        required: [:name], 
+        properties: {
+          name: {type: :string, description: "Name of the permission"}, 
+          read: {type: :boolean, description: "Permission to read"}, 
+          write: {type: :boolean, description: "Permission to write"}
+        }
+      }, 
+      description: "Permissions associated with the user"
+    },
+    role: {type: :string, description: "Role of the user", enum: ["member", "manager"], default: "member"},
+    profile_details: {
+      type: :object,
+      required: [],
+      properties: {
+        bio: {type: :string, description: "Short biography of the user"},
+        hobbies: {type: :array, items: {type: :string}, description: "Tags associated with the user"},
+        social_links: {
+          type: :object, 
+          required: [], 
+          properties: {
+            github: {type: :string, format: "uri", description: "GitHub profile URL"}, 
+            mastodon: {type: :string, format: "uri", description: "Mastodon profile URL"}
+          }, 
+          description: "Some social networks"
+        }
+      }
+    }
+  },
+  additionalProperties: false
+}
+```
+
+### JSON schema for validation
+
+You can check the validation JSON schema for a specific version of your request:
+
+```ruby
+UserCreateRequest.to_validation_schema(version: "2025-06")
+```
+
+Output:
+```ruby
+{
+  type: :object,
+  description: "User Create Request",
+  required: [:first_name, :last_name, :email, :address],
+  properties: {
+    first_name: {type: :string, description: "The first name of the user", maxLength: 50},
+    last_name: {type: :string, description: "The last name of the user", maxLength: 50},
+    email: {type: :string, format: "email", description: "The email address of the user"},
+    birth_date: {type: :string, format: "date", description: "The birth date of the user"},
+    address: { # from the AddressCreateRequest
+      type: :object,
+      description: "Address Create Request",
+      required: [:street, :city, :postal_code, :country],
+      properties: {
+        street: {type: :string, description: "Street address"}, 
+        city: {type: :string, description: "City of residence"}, 
+        postal_code: {type: :string, description: "Postal code"}, 
+        country: {type: :string, description: "Country of residence"}
+      },
+      additionalProperties: false
+    },
+    permissions: {
+      type: :array,
+      items: {
+        type: :object,
+        required: [:name],
+        properties: {
+          name: {type: :string, description: "Name of the permission"},
+          read: {type: :boolean, description: "Permission to read"},
+          write: {type: :boolean, description: "Permission to write"}
+        }
+      },
+      description: "Permissions associated with the user"
+    },
+    role: {type: :string, description: "Role of the user", enum: ["member", "manager"], default: "member"},
+    profile_details: {
+      type: :object,
+      required: [],
+      properties: {
+        bio: {type: :string, description: "Short biography of the user"},
+        hobbies: {type: :array, items: {type: :string}, description: "Tags associated with the user"},
+        social_links: {
+          type: :object,
+          required: [],
+          properties: {
+            github: {type: :string, format: "uri", description: "GitHub profile URL"},
+            mastodon: {type: :string, format: "uri", description: "Mastodon profile URL"}
+          },
+          description: "Some social networks"
+        }
+      }
+    }
+  },
+  additionalProperties: false
+}
+```
+
+You can also validate it to ensure it meets the JSON Schema standards:
+
+```ruby
+UserCreateRequest.validate_schema(version: "2025-06") # => true/false
+```
+
+## Core Features
+
+### Schema Definition and Validation
+
+See the example above for how to define a request schema. Verquest provides a DSL to define your API requests with various component types and helper methods based on JSON Schema, which is also used in [OpenAPI specification](https://swagger.io/specification/#schema-object-examples) for components.
+
+The JSON schema can be used for both validation of incoming parameters and for generating OpenAPI documentation components.
+
+#### Component types
+
+- `field`: Represents a scalar value (string, integer, boolean, etc.).
+- `object`: Represents a JSON object with properties.
+- `array`: Represents a JSON array with scalar items.
+- `collection`: Represents a array of objects defined manually or by a reference to another request.
+- `reference`: Represents a reference to another request, allowing you to reuse existing request structures.
+
+#### Helper methods
+
+- `description`: Adds a description to the request or per version.
+- `schema_options`: Allows you to set additional options for the JSON Schema, such as `additional_properties` for request or per version. All fields (except `reference`) can be defined with options like `required`, `format`, `min_lenght`, `max_length`, etc. all in snake case.
+- `with_options`: Allows you to define multiple fields with the same options, reducing repetition.
+
+### Versioning
+
+Verquest allows you to define multiple versions of your API requests, making it easy to evolve your API over time:
+
+```ruby
+class UserCreateRequest < Verquest::Base
+  version "2025-04" do    
+    field :name, type: :string, required: true
+    field :email, type: :string, format: "email", required: true
+
+    field :street, type: :string
+    field :city, type: :string
+  end
+  
+  # Implicit inheritance from the previous version
+  version "2025-06", exclude_properties: %i[street city] do
+    field :phone, type: :string
+    
+    # Replace street and city with a structured address object with zip
+    object :address do
+      field :street, type: :string
+      field :city, type: :string
+      field :zip, type: :string
+    end
+  end
+  
+  # Disabled inheritance, `inherit` can also be set to a specific version
+  version "2025-08", inherit: false do
+    field :name, type: :string, required: true
+    field :email, type: :string, format: "email", required: true
+    field :phone, type: :string
+    
+    # Replace address with a more structured version
+    object :address do
+      field :street_line1, type: :string, required: true
+      field :street_line2, type: :string
+      field :city, type: :string, required: true
+      field :state, type: :string
+      field :postal_code, type: :string, required: true
+      field :country, type: :string, required: true
+    end
+  end
+end
+```
+
+Internal `Verquest::VersionResolver` is then used to resolve the right version for the one specified in the call. It implements a "downgrading" strategy - when an exact version match isn't found, it returns the closest earlier version.
+
+Example:
+```ruby
+UserCreateRequest.process(params, version: "2025-05") # => use the defined version "2025-04"
+UserCreateRequest.process(params, version: "2025-06") # => use the defined version "2025-06"
+UserCreateRequest.process(params, version: "2025-07") # => use the closest earlier version "2025-06"
+UserCreateRequest.process(params, version: "2025-08") # => use the defined version "2025-08"
+UserCreateRequest.process(params, version: "2025-10") # => use the closest earlier version "2025-08"
+```
+
+This is used across all referenced requests, so if you have a `UserRequest` that references an `AddressCreateRequest`, it will also resolve the correct version of the `AddressCreateRequest` based on the initial requested version (as the `AddressCreateRequest` can have different versions defined).
+
+The goal here is to avoid redefining the same request structure in multiple versions when there are no changes, and to facilitate the easy evolution of API requests over time. When a new API version is created and there are no changes to the requests, you don't need to update anything.
+
+### Mapping request structure
+
+Verquest's mapping system allows transforming external API request structures into your internal application data structures.
+
+Here’s a short example: we store the address in the same table as the user internally, but the API request structure is different.
+
+```ruby
+class UserCreateRequest < Verquest::Base
+  version "2025-06", exclude_properties: %i[street city] do
+    field :full_name, type: :string, map: "name"
+    field :email, type: :string, format: "email", required: true
+    field :phone, type: :string
+    
+    object :address do
+      field :street, type: :string, map: "/address_street"
+      field :city, type: :string, map: "/address_city"
+      field :postal_code, type: :string, map: "/address_zip"
+    end
+  end
+end
+```
+
+When called with `UserCreateRequest.process(params)`, the `address` object will be mapped to the internal structure with keys `address_street`, `address_city`, and `address_zip`.
+
+Example request params
+```ruby
+{
+  "full_name": "John Doe",
+  "email": "john@doe.com",
+  "phone": "1234567890",
+  "address": {
+    "street": "123 Main St",
+    "city": "Springfield",
+    "postal_code": "12345"
+  }
+}
+```
+
+Will be transformed to:
+```ruby
+{
+  "name": "John Doe",
+  "email": "john@doe.com",
+  "phone": "1234567890",
+  "address_street": "123 Main St",
+  "address_city": "Springfield",
+  "address_zip": "12345"
+}
+````
+
+What you can use:
+- `/` to reference the root of the request structure
+- `nested.structure` use dot notation to reference nested structures
+- if the `map` is not set, the field name will be used as the key in the internal structure
+
+There are some limitations and the implementation can be improved, but it should works for most common use cases.
+
+See the mapping test (in `test/verquest/base_test.rb`) for more examples of mapping.
+
+### Component Generation for OpenAPI
+
+Generate JSON Schema, component name and reference for OpenAPI documentation:
+
+```ruby
+UserCreateRequest.component_name # => "UserCreateRequest"
+UserCreateRequest.to_ref # => "#/components/schemas/UserCreateRequest"
+component_schema = UserCreateRequest.to_schema(version: "2025-06")
+```
+
+## Configuration
+
+Configure Verquest globally:
+
+```ruby
+Verquest.configure do |config|
+  # Enable validation by default
+  config.validate_params = true # default
+  
+  # Set the default version to use
+  config.current_version = -> { Current.api_version }
+  
+  # Set the JSON Schema version
+  config.json_schema_version = :draft6 # default
+  
+  # Set the error handling strategy for processing params
+  config.validation_error_handling = :raise # default, can be set also to :result
+  
+  # Remove extra root keys from provided params
+  config.remove_extra_root_keys = true # default
+  
+  # Set custom version resolver
+  config.version_resolver = CustomeVersionResolver # default is `Verquest::VersionResolver`
+end
 ```
 
-## Usage
+## Documentation
 
-TODO: Write usage instructions here
+For detailed documentation, please visit the [YARD documentation](https://www.rubydoc.info/gems/verquest).
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `gem_version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/verquest. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/verquest/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/CiTroNaK/verquest. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/CiTroNaK/verquest/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +443,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Verquest project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/verquest/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Verquest project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/CiTroNaK/verquest/blob/main/CODE_OF_CONDUCT.md).

data/lib/verquest/base/helper_class_methods.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Verquest
+  # Helper methods for Verquest::Base class methods
+  #
+  # This module contains utility methods for working with string and hash
+  # transformations. It provides methods for converting between different
+  # naming conventions (snake_case to camelCase) which is particularly useful
+  # when working with JSON Schema properties.
+  #
+  # @api private
+  module Base::HelperClassMethods
+    # Converts hash keys from snake_case to camelCase format
+    #
+    # Transforms all keys in the given hash from snake_case (e.g., "max_length")
+    # to camelCase (e.g., "maxLength") format, which is commonly used in JSON Schema.
+    # The transformation happens in place, modifying the original hash.
+    #
+    # @param hash [Hash] The hash containing snake_case keys
+    # @return [Hash] The same hash with keys transformed to camelCase
+    def camelize(hash)
+      hash.transform_keys! { |key| snake_to_camel(key.to_s).to_sym }
+    end
+
+    # Converts a snake_case string to camelCase
+    #
+    # Takes a string in snake_case format (e.g., "max_length") and converts it
+    # to camelCase format (e.g., "maxLength") by capitalizing each word after
+    # the first one and removing underscores.
+    #
+    # @param str [String] The snake_case string to convert
+    # @return [String] The converted camelCase string
+    def snake_to_camel(str)
+      str.split("_").inject { |memo, word| memo + word.capitalize }
+    end
+  end
+end