versponse 0.1.0 → 0.2.0

data/lib/versponse.rb

@@ -1,8 +1,170 @@
 # frozen_string_literal: true
 
-require_relative "versponse/version"
+require "zeitwerk"
+require "json"
+require "time"
 
+require_relative "versponse/gem_version"
+
+loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
+loader.ignore("#{File.dirname(__FILE__)}/versponse/gem_version.rb")
+loader.inflector.inflect("dsl" => "DSL", "open_api" => "OpenAPI", "json_value" => "JSONValue")
+loader.push_dir(File.dirname(__FILE__))
+loader.setup
+
+# Versponse serializes objects to JSON-ready hashes with a versioned DSL
+# and generates an OpenAPI schema for every response, version and view.
+#
+# @example
+#   class UserResponse < Versponse::Base
+#     version "2025-09" do
+#       field :id, type: :string
+#       field :name, type: :string
+#     end
+#   end
+#
+#   UserResponse.serialize(user, version: "2025-09") # => {"id" => "u_1", "name" => "Ann"}
 module Versponse
-  class Error < StandardError; end
-  # Your code goes here...
+  # Base error for everything Versponse raises
+  Error = Class.new(StandardError)
+
+  # Raised when the DSL is used incorrectly
+  DefinitionError = Class.new(Error)
+
+  # Raised when to_validation_schema(property:) names an unknown property
+  PropertyNotFoundError = Class.new(Error)
+
+  # Raised when no version matches the requested one
+  VersionNotFoundError = Class.new(Error)
+
+  # Raised when a view does not exist in the resolved version
+  ViewNotFoundError = Class.new(Error)
+
+  # Raised when reading a value from the serialized object fails
+  class ExtractionError < Error
+    # @return [String] the plan where extraction failed, like "UserResponse[2025-09/default]"
+    attr_reader :label
+    # @return [Array<String>] output keys from the plan down to the failing value
+    attr_reader :keys
+    # @return [String] message of the original error
+    attr_reader :detail
+
+    # @param label [String] plan label
+    # @param keys [Array<String>] output keys leading to the failing value
+    # @param detail [String] message of the original error
+    def initialize(label:, keys:, detail:)
+      @label = label
+      @keys = keys
+      @detail = detail
+      super("#{[label, *keys].join(".")}: #{detail}")
+    end
+  end
+
+  # Raised when validate_output is on and the output does not match its schema
+  class InvalidOutputError < Error
+    # @return [Array<Hash>] errors with :pointer, :type, :message and :details
+    attr_reader :errors
+
+    # @param message [String] error message
+    # @param errors [Array<Hash>] validation errors
+    def initialize(message, errors:)
+      super(message)
+      @errors = errors
+    end
+  end
+
+  # Raised when expand: names paths that match no expandable association (config.unknown_expand = :raise)
+  class InvalidExpandError < Error
+    # @return [Array<String>] the unknown paths
+    attr_reader :paths
+
+    # @param paths [Array<String>] unknown paths
+    def initialize(paths:)
+      @paths = paths
+      super("Unknown expand paths: #{paths.map(&:inspect).join(", ")}")
+    end
+  end
+
+  # Raised when fields: names unknown paths, or paths below associations the render doesn't expand
+  # (config.unknown_fields = :raise)
+  class InvalidFieldsError < Error
+    # @return [Array<String>] the invalid paths
+    attr_reader :paths
+
+    # @param paths [Array<String>] invalid paths
+    # @param reasons [Hash{String => String}] why each path is invalid
+    def initialize(paths:, reasons:)
+      @paths = paths
+      super("Invalid fields paths: #{paths.map { |path| "#{path.inspect} (#{reasons.fetch(path)})" }.join(", ")}")
+    end
+  end
+
+  class << self
+    # @return [Versponse::Configuration] global configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @yieldparam configuration [Versponse::Configuration]
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+
+    # Clears compiled plans and schemas of every response class (lazily, on each class's next use).
+    # Setting a configuration value that changes output calls it already.
+    #
+    # @return [void]
+    def reset_caches!
+      Registry.clear_canonical
+      @cache_generation = cache_generation + 1
+    end
+
+    # @return [Integer] how many times the caches were reset; each class compares it and clears its own caches when behind
+    # @api private
+    def cache_generation
+      @cache_generation ||= 0
+    end
+
+    # @param version [String] requested version
+    # @param classes [Array<Class>] response classes (default: every loaded one; eager load your app first)
+    # @return [Hash{String => Hash}] components/schemas for an OpenAPI document
+    # @raise [Versponse::DefinitionError] when two components share a name
+    def components(version:, classes: Registry.classes)
+      Components.call(version:, classes:)
+    end
+
+    # Compiles every plan and schema of every supported version and view, surfacing definition errors at boot.
+    # A class with supported_versions compiles the names its range serves, such as "preview" for a
+    # min: "preview" class whose only block is 2025-09.
+    #
+    # @param classes [Array<Class>] response classes (default: every loaded one)
+    # @return [Array<Class>] the classes
+    # @raise [Versponse::DefinitionError] when a supported_versions max sorts before every declared version
+    def eager_load!(classes: Registry.classes)
+      classes.each do |klass|
+        klass.versponse.supported_version_names.each do |version|
+          klass.versponse.resolve(version).view_names.each do |view|
+            klass.versponse.plan(version:, view:)
+            klass.to_schema(version:, view:)
+            klass.to_validation_schema(version:, view:)
+          end
+        end
+        check_served_references(klass)
+      end
+    end
+
+    private
+
+    # Nested classes resolve each request on their own, so a reference can break at a version the class
+    # serves but doesn't declare; check every registered one it serves
+    def check_served_references(klass)
+      Registry.version_names.each do |version|
+        klass.versponse.check_references!(version)
+      rescue VersionNotFoundError
+        next
+      end
+    end
+  end
 end

metadata

@@ -1,17 +1,48 @@
 --- !ruby/object:Gem::Specification
 name: versponse
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Petr Hlavicka
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: ''
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: Versponse describes API responses with a Ruby DSL shared with verquest,
+  one definition per API version, with blueprinter-style views. It renders objects
+  to JSON-ready hashes and generates an OpenAPI schema for every response, version
+  and view.
 email:
-- petr@hlavicka.cz
+- yes@petr.codes
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -23,15 +54,123 @@ files:
 - README.md
 - Rakefile
 - lib/versponse.rb
+- lib/versponse/base.rb
+- lib/versponse/base/class_methods.rb
+- lib/versponse/base/dsl.rb
+- lib/versponse/builder.rb
+- lib/versponse/cache.rb
+- lib/versponse/callable.rb
+- lib/versponse/class_policies.rb
+- lib/versponse/collapse_if_plan.rb
+- lib/versponse/collections.rb
+- lib/versponse/components.rb
+- lib/versponse/condition.rb
+- lib/versponse/configuration.rb
+- lib/versponse/const_as_enum.rb
+- lib/versponse/context_override.rb
+- lib/versponse/context_override/call.rb
+- lib/versponse/context_override/merge.rb
+- lib/versponse/context_plan.rb
+- lib/versponse/deep_copy.rb
+- lib/versponse/deep_freeze.rb
+- lib/versponse/discriminated_plan.rb
+- lib/versponse/error_policy.rb
+- lib/versponse/error_policy/recovery.rb
+- lib/versponse/expansion.rb
+- lib/versponse/extractors.rb
+- lib/versponse/extractors/block.rb
+- lib/versponse/extractors/fallback.rb
+- lib/versponse/extractors/itself.rb
+- lib/versponse/extractors/key.rb
+- lib/versponse/extractors/path.rb
+- lib/versponse/field_order.rb
+- lib/versponse/field_type.rb
+- lib/versponse/formatters.rb
+- lib/versponse/gem_version.rb
+- lib/versponse/inline_validation.rb
+- lib/versponse/inline_validation/builder.rb
+- lib/versponse/inline_validation/state.rb
+- lib/versponse/internals.rb
+- lib/versponse/json_value.rb
+- lib/versponse/lazy_plan.rb
+- lib/versponse/naming.rb
+- lib/versponse/object_schema.rb
+- lib/versponse/open_api.rb
+- lib/versponse/open_api/builder.rb
+- lib/versponse/open_api/component_set.rb
+- lib/versponse/open_api/declarations.rb
+- lib/versponse/open_api/document.rb
+- lib/versponse/open_api/ref_check.rb
+- lib/versponse/open_api/rswag_specs.rb
+- lib/versponse/open_api/sources.rb
+- lib/versponse/open_api/values.rb
+- lib/versponse/output_validator.rb
+- lib/versponse/pattern.rb
+- lib/versponse/plan.rb
+- lib/versponse/properties/array.rb
+- lib/versponse/properties/base.rb
+- lib/versponse/properties/collection.rb
+- lib/versponse/properties/const.rb
+- lib/versponse/properties/container.rb
+- lib/versponse/properties/enum.rb
+- lib/versponse/properties/field.rb
+- lib/versponse/properties/item_one_of.rb
+- lib/versponse/properties/object.rb
+- lib/versponse/properties/one_of.rb
+- lib/versponse/properties/reference.rb
+- lib/versponse/references.rb
+- lib/versponse/registry.rb
+- lib/versponse/schema_context.rb
+- lib/versponse/schema_merge.rb
+- lib/versponse/selection.rb
+- lib/versponse/selection/scope.rb
+- lib/versponse/selection_schema.rb
+- lib/versponse/steps/checked.rb
+- lib/versponse/steps/checked_read.rb
+- lib/versponse/steps/checked_read_formatted.rb
+- lib/versponse/steps/checked_value.rb
+- lib/versponse/steps/const.rb
+- lib/versponse/steps/nested.rb
+- lib/versponse/steps/one_of.rb
+- lib/versponse/steps/read.rb
+- lib/versponse/steps/read_formatted.rb
+- lib/versponse/steps/value.rb
+- lib/versponse/supported_versions.rb
+- lib/versponse/validator.rb
+- lib/versponse/validator/all.rb
+- lib/versponse/validator/array_check.rb
+- lib/versponse/validator/boolean_check.rb
+- lib/versponse/validator/both.rb
+- lib/versponse/validator/class_check.rb
+- lib/versponse/validator/closed_object_check.rb
+- lib/versponse/validator/combinator.rb
+- lib/versponse/validator/compiler.rb
+- lib/versponse/validator/constant.rb
+- lib/versponse/validator/date_time_check.rb
+- lib/versponse/validator/format_check.rb
+- lib/versponse/validator/integer_check.rb
+- lib/versponse/validator/nullable_check.rb
+- lib/versponse/validator/number_check.rb
+- lib/versponse/validator/object_check.rb
+- lib/versponse/validator/ref.rb
+- lib/versponse/validator/root.rb
+- lib/versponse/validator/string_check.rb
+- lib/versponse/validator/string_keys.rb
+- lib/versponse/validator/type_check.rb
+- lib/versponse/validator/value_check.rb
+- lib/versponse/variant_dispatcher.rb
 - lib/versponse/version.rb
-- sig/versponse.rbs
-homepage: https://github.com/CiTroNaK/versponse
+- lib/versponse/version_resolver.rb
+- lib/versponse/versions.rb
+- lib/versponse/view.rb
+- lib/versponse/wrapper.rb
+homepage: https://github.com/verquest/versponse
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/CiTroNaK/versponse
-  source_code_uri: https://github.com/CiTroNaK/versponse
-  changelog_uri: https://github.com/CiTroNaK/versponse/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/verquest/versponse
+  changelog_uri: https://github.com/verquest/versponse/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -39,14 +178,14 @@ 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: 4.0.17
 specification_version: 4
-summary: ''
+summary: Versioned JSON response serializer with views and OpenAPI schemas
 test_files: []

data/sig/versponse.rbs

@@ -1,4 +0,0 @@
-module Versponse
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end