paradocs 1.0.22

data/lib/paradocs.rb

@@ -0,0 +1,36 @@
+require "paradocs/version"
+require "paradocs/support"
+require "paradocs/registry"
+require "paradocs/field"
+require "paradocs/results"
+require "paradocs/schema"
+require "paradocs/context"
+require "paradocs/base_policy"
+require 'ostruct'
+
+module Paradocs
+  def self.registry
+    @registry ||= Registry.new
+  end
+
+  def self.policy(name, plcy = nil, &block)
+    registry.policy name, plcy, &block
+  end
+
+  def self.config
+    @config ||= OpenStruct.new(
+      explicit_errors:     false,
+      whitelisted_keys:    [],
+      default_schema_name: :schema,
+      meta_prefix:         "_"
+    )
+  end
+
+  def self.configure
+    yield self.config if block_given?
+    self.config
+  end
+end
+
+require 'paradocs/default_types'
+require 'paradocs/policies'

data/paradocs.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'paradocs/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "paradocs"
+  spec.version       = Paradocs::VERSION
+  spec.authors       = ["Ismael Celis", "Maxim Tkachenko"]
+  spec.email         = ["ismaelct@gmail.com", "tkachenko.maxim.w@gmail.com"]
+  spec.description   = %q{Flexible DSL for declaring allowed parameters focused on DRY validation that gives you opportunity to generate API documentation on-the-fly.}
+  spec.summary       = %q{A huge add-on for original gem mostly focused on retrieving the more metadata from declared schemas as possible.}
+  spec.homepage      = "https://github.com/mtkachenk0/paradocs"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "rake", "~> 0"
+  spec.add_development_dependency "rspec", '3.4.0'
+  spec.add_development_dependency "pry", "~> 0"
+end

data/spec/custom_block_validator_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+
+describe 'custom block validator' do
+  Paradocs.policy :validate_if do
+    eligible do |options, value, key, payload|
+      options.all? do |key, value|
+        payload[key] == value
+      end
+    end
+  end
+
+  it 'works if I just define an :eligible block' do
+    schema = Paradocs::Schema.new do
+      field(:name).policy(:validate_if, age: 40).present
+      field(:age).type(:integer)
+    end
+
+    expect(schema.resolve(age: 30).errors.any?).to be false
+    expect(schema.resolve(age: 40).errors.any?).to be true # name is missing
+  end
+
+  before do
+    expect(Paradocs.registry.policies.values.map(&:policy_name)).to all(be)
+  end
+
+  describe "error handling" do
+    Paradocs.policy :strict_validation do
+        register_error ArgumentError
+        register_silent_error RuntimeError
+
+        validate do |value, key, payload|
+          raise ArgumentError.new("test") if value > 50
+          raise RuntimeError.new("value should not exceed 30") if value > 30
+          true
+        end
+
+        coerce do |value, key, context|
+          value / 0 if value > 100
+          value
+        end
+      end
+
+      let(:schema) do
+        Paradocs::Schema.new do
+          field(:age).type(:integer).policy(:strict_validation)
+        end
+      end
+
+    context "with disabled explicit errors" do
+      it "works fine if value is valid" do
+        expect(schema.resolve(age: 20).errors.any?).to be false
+      end
+
+      it "catches silent errors and uses the error.message as validation failure message" do
+        expect(schema.resolve(age: 31).errors).to eq({"$.age" => ["value should not exceed 30"]})
+      end
+
+      it "raises the very registered error to the highest level" do
+        expect { schema.resolve(age: 51) }.to raise_error(ArgumentError).with_message("test")
+      end
+
+      it "catches unregistered error and uses the policy.message as validation failure message" do
+        expect(schema.resolve(age: 101).errors).to eq({"$.age" => ["is invalid"]})
+      end
+    end
+
+    context "with enabled explicit errors" do
+      before { allow(Paradocs.config).to receive(:explicit_errors) { true } }
+
+      it "works fine if value is valid" do
+        expect(schema.resolve(age: 20).errors.any?).to be false
+      end
+
+      it "catches silent errors and uses the error.message as validation failure message" do
+        expect(schema.resolve(age: 31).errors).to eq({"$.age" => ["value should not exceed 30"]})
+      end
+
+      it "raises the very registered error to the highest level" do
+        expect { schema.resolve(age: 51) }.to raise_error(ArgumentError).with_message("test")
+      end
+
+      it "catches unregistered error and raises Configuration error" do
+        expect { schema.resolve(age: 101).errors }.to raise_error(Paradocs::ConfigurationError)
+          .with_message("ZeroDivisionError should be registered in the policy")
+      end
+    end
+  end
+end

data/spec/custom_validator.rb

@@ -0,0 +1,61 @@
+require "spec_helper"
+
+describe "custom validator" do
+  let(:validator) do
+    class PresentIf < Paradocs::BasePolicy
+      def initialize(condition)
+        @condition = @condition
+      end
+
+      def validate(value, key, payload)
+        value.present? && key.present?
+      end
+
+      def eligible?(value, key, payload)
+        condition.call(value, key, payload)
+      end
+    end
+    PresentIf
+  end
+
+  describe "registration" do
+    it "doesn't raise error if validator is built properly" do
+      expect { Paradocs.policy :present_if, validator }.to_not raise_error
+      expect(Paradocs.registry.policies[:present_if]).to eq(validator)
+    end
+
+    it "raises ConfigurationError if validator class doesn't respond to required methods" do
+      expect { Paradocs.policy :bad_validator, Class.new }.to raise_error(Paradocs::ConfigurationError)
+        .with_message(/Policy .* should respond to \[:valid\?, :coerce, :eligible\?, :meta_data, :policy_name\]/)
+    end
+
+    it "raises ConfigrationError if child validator class overrides #valid? method" do
+      expect do
+        Paradocs.policy(
+          :bad_validator,
+          Class.new(Paradocs::BasePolicy) do
+            define_method(:valid?) { true }
+          end
+        )
+      end.to raise_error(Paradocs::ConfigurationError)
+        .with_message(/Overriding #valid\? in .* is forbidden\. Override #validate instead/)
+    end
+
+    context "with enabled explicit_errors" do
+      before { allow(Paradocs.config).to receive(:explicit_errors) { true } }
+
+      it "raises ConfigurationError if custom validator doesn't implement .errors method" do
+        validator = Class.new do
+          def valid?; end
+          def coerce; end
+          def eligible?; end
+          def meta_data; end
+          def policy_name; end
+        end
+
+        expect { Paradocs.policy :malformed_validator, validator }.to raise_error(Paradocs::ConfigurationError)
+          .with_message(/Policy .* should respond to \.errors method/)
+      end
+    end
+  end
+end

data/spec/dsl_spec.rb

@@ -0,0 +1,175 @@
+require 'spec_helper'
+require "paradocs/dsl"
+
+describe "classes including DSL module" do
+  class Parent
+    include Paradocs::DSL
+
+    schema :extras, search_type: :string do |opts|
+      field(:search).policy(opts[:search_type])
+    end
+
+    schema(age_type: :integer) do |opts|
+      field(:title).policy(:string)
+      field(:age).policy(opts[:age_type])
+    end
+  end
+
+  class Child < Parent
+    schema :extras do
+      field(:query).type(:string)
+    end
+
+    schema(age_type: :string) do
+      field(:description).policy(:string)
+    end
+  end
+
+  class GrandChild < Child
+    schema :extras, search_type: :integer
+
+    schema(age_type: :integer)
+  end
+
+  describe "#schema" do
+    let(:input) {
+      {
+        title: "A title",
+        age: 38,
+        description: "A description"
+      }
+    }
+
+    it "merges parent's schema into child's" do
+      parent_output = Parent.schema.resolve(input).output
+      child_output = Child.schema.resolve(input).output
+
+      expect(parent_output.keys).to match_array([:title, :age])
+      expect(parent_output[:title]).to eq "A title"
+      expect(parent_output[:age]).to eq 38
+
+      expect(child_output.keys).to match_array([:title, :age, :description])
+      expect(child_output[:title]).to eq "A title"
+      expect(child_output[:age]).to eq "38"
+      expect(child_output[:description]).to eq "A description"
+
+      # named schema
+      parent_output = Parent.schema(:extras).resolve(search: 10, query: 'foo').output
+      child_output = Child.schema(:extras).resolve(search: 10, query: 'foo').output
+
+      expect(parent_output.keys).to match_array([:search])
+      expect(parent_output[:search]).to eq "10"
+      expect(child_output.keys).to match_array([:search, :query])
+      expect(child_output[:search]).to eq "10"
+      expect(child_output[:query]).to eq "foo"
+    end
+
+    it "inherits options" do
+      grand_child_output = GrandChild.schema.resolve(input).output
+
+      expect(grand_child_output.keys).to match_array([:title, :age, :description])
+      expect(grand_child_output[:title]).to eq "A title"
+      expect(grand_child_output[:age]).to eq 38
+      expect(grand_child_output[:description]).to eq "A description"
+
+      # named schema
+      grand_child_output = GrandChild.schema(:extras).resolve(search: "100", query: "bar").output
+      expect(grand_child_output.keys).to match_array([:search, :query])
+      expect(grand_child_output[:search]).to eq 100
+    end
+  end
+
+  describe "inheriting schema policy" do
+    let!(:a) {
+      Class.new do
+        include Paradocs::DSL
+
+        schema.policy(:present) do
+          field(:title).policy(:string)
+        end
+      end
+    }
+
+    let!(:b) {
+      Class.new(a)
+    }
+
+    it "inherits policy" do
+      results = a.schema.resolve({})
+      expect(results.errors["$.title"]).not_to be_empty
+
+      results = b.schema.resolve({})
+      expect(results.errors["$.title"]).not_to be_empty
+    end
+  end
+
+  describe "overriding schema policy" do
+    let!(:a) {
+      Class.new do
+        include Paradocs::DSL
+
+        schema.policy(:present) do
+          field(:title).policy(:string)
+        end
+      end
+    }
+
+    let!(:b) {
+      Class.new(a) do
+        schema.policy(:declared)
+      end
+    }
+
+    it "does not mutate parent schema" do
+      results = a.schema.resolve({})
+      expect(results.errors).not_to be_empty
+
+      results = b.schema.resolve({})
+      expect(results.errors).to be_empty
+    end
+  end
+
+  describe "removes fields defined in the parent class" do
+    let!(:a) {
+      Class.new do
+        include Paradocs::DSL
+
+        schema do
+          field(:title).policy(:string)
+        end
+      end
+    }
+
+    let!(:b) {
+      Class.new(a) do
+        schema.ignore(:title) do
+          field(:age)
+        end
+      end
+    }
+
+    it "removes inherited field from child class" do
+      results = a.schema.resolve({title: "Mr.", age: 20})
+      expect(results.output).to eq({title: "Mr."})
+
+      results = b.schema.resolve({title: "Mr.", age: 20})
+      expect(results.output).to eq({age: 20})
+    end
+  end
+
+  describe "passing other schema or form in definition" do
+    it 'applies schema' do
+      a = Paradocs::Schema.new do
+        field(:name).policy(:string)
+        field(:age).policy(:integer).default(40)
+      end
+      b = Class.new do
+        include Paradocs::DSL
+        schema a
+      end
+
+      results = b.schema.resolve(name: 'Neil')
+      expect(results.output).to eq({name: 'Neil', age: 40})
+    end
+  end
+end

data/spec/expand_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Paradocs::Schema do
+  it "expands fields dynamically" do
+    schema = described_class.new do
+      field(:title).type(:string).present
+      expand(/^attr_(.+)/) do |match|
+        field(match[1]).type(:string)
+      end
+      expand(/^validate_(.+)/) do |match|
+        field(match[1]).type(:string).present
+      end
+    end
+
+    out = schema.resolve({
+      title: "foo",
+      :"attr_Attribute 1" => "attr 1",
+      :"attr_Attribute 2" => "attr 2",
+      :"validate_valid_attr" => "valid",
+      :"validate_invalid_attr" => "",
+    })
+
+    expect(out.output[:title]).to eq 'foo'
+    expect(out.output[:"Attribute 1"]).to eq 'attr 1'
+    expect(out.output[:"Attribute 2"]).to eq 'attr 2'
+
+    expect(out.errors['$.invalid_attr']).to eq ['is required and value must be present']
+  end
+end