paradocs 1.0.22

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "paradocs"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/lib/paradocs/base_policy.rb

@@ -0,0 +1,123 @@
+module Paradocs
+  class BasePolicy
+    def self.build(name, meth, &block)
+      klass = Class.new(self)
+      klass.public_send(meth, &block)
+      klass.policy_name = name
+      klass
+    end
+
+    def self.message(&block)
+      @message_block = block if block_given?
+      @message_block
+    end
+
+    def self.validate(&validate_block)
+      @validate_block = validate_block if block_given?
+      @validate_block
+    end
+
+    def self.coerce(&coerce_block)
+      @coerce_block = coerce_block if block_given?
+      @coerce_block
+    end
+
+    def self.eligible(&block)
+      @eligible_block = block if block_given?
+      @eligible_block
+    end
+
+    def self.meta_data(&block)
+      @meta_data_block = block if block_given?
+      @meta_data_block
+    end
+
+    %w(error silent_error).each do |name|
+      getter = "#{name}s"
+      define_singleton_method(getter) do
+        parent_errors = superclass.respond_to?(getter) ? superclass.send(getter) : []
+        parent_errors | (instance_variable_get("@#{getter}") || instance_variable_set("@#{getter}", []))
+      end
+
+      define_singleton_method("register_#{name}") do |*exceptions| # TODO: spec
+        # [Exception, as: :helper_method] or [Exception1, Exception2....]
+        only_errors = []
+        exceptions.each_with_index do |ex, index|
+          if ex.is_a? Hash
+            exception = exceptions[index - 1]
+            define_method(ex[:as]) { exception }
+            next
+          end
+          next unless ex.is_a?(Class) || ex < StandardError
+          only_errors << ex
+        end
+        instance_variable_set("@#{getter}", ((self.public_send(getter) || []) + only_errors).uniq)
+      end
+
+      define_method(getter) do
+        instance_variable_set("@#{getter}", self.class.send("register_#{name}") || [])
+      end
+    end
+
+    def self.policy_name=(name)
+      @policy_name = name
+    end
+
+    def self.policy_name
+      @policy_name || self.name.split("::").last.downcase.to_sym
+    end
+
+    attr_accessor :environment
+    def initialize(*args)
+      @init_params = args
+    end
+
+    def eligible?(value, key, payload)
+      args = (init_params + [value, key, payload])
+      (self.class.eligible || ->(*) { true }).call(*args)
+    end
+
+    def coerce(value, key, context)
+      (self.class.coerce || ->(v, *_) { v }).call(value, key, context)
+    end
+
+    def valid?(value, key, payload)
+      args = (init_params + [value, key, payload])
+      @message = self.class.message.call(*args) if self.class.message
+      validate(*args)
+    end
+
+    def meta_data
+      return self.class.meta_data.call(*init_params) if self.class.meta_data
+      meta
+    end
+
+    def validate(*args)
+      (self.class.validate || ->(*) { true }).call(*args)
+    end
+
+    def policy_name
+      (self.class.policy_name || self.to_s.demodulize.underscore).to_sym
+    end
+
+    def message
+      @message ||= 'is invalid'
+    end
+
+    protected
+
+    def validate(*args)
+      (self.class.validate || ->(*args) { true }).call(*args)
+    end
+
+    private
+
+    def meta
+      @meta = {self.class.policy_name => {errors: self.class.errors}}
+    end
+
+    def init_params
+      @init_params ||= [] # safe default if #initialize was overwritten
+    end
+  end
+end

data/lib/paradocs/context.rb

@@ -0,0 +1,54 @@
+module Paradocs
+  class Top
+    attr_reader :errors
+
+    def initialize
+      @errors = {}
+    end
+
+    def add_error(key, msg)
+      errors[key] ||= []
+      errors[key] << msg
+    end
+  end
+
+  class Context
+    attr_reader :environment
+    def initialize(path=nil, top=Top.new, environment={}, subschemes={})
+      @top = top
+      @path = Array(path).compact
+      @environment = environment
+      @subschemes = subschemes
+    end
+
+    def subschema(subschema_name)
+      subschema = @subschemes[subschema_name]
+      return unless subschema
+      @subschemes.merge!(subschema.subschemes)
+      subschema
+    end
+
+    def errors
+      top.errors
+    end
+
+    def add_error(msg)
+      top.add_error(string_path, msg)
+    end
+
+    def sub(key)
+      self.class.new(path + [key], top, environment, @subschemes)
+    end
+
+    protected
+    attr_reader :path, :top
+
+    def string_path
+      path.reduce(['$']) do |m, segment|
+        m << (segment.is_a?(Integer) ? "[#{segment}]" : ".#{segment}")
+        m
+      end.join
+    end
+  end
+
+end

data/lib/paradocs/default_types.rb

@@ -0,0 +1,95 @@
+require "date"
+
+module Paradocs
+  # type coercions
+  Paradocs.policy :integer do
+    coerce do |v, k, c|
+      v.to_i
+    end
+
+    meta_data do
+      {type: :integer}
+    end
+  end
+
+  Paradocs.policy :number do
+    coerce do |v, k, c|
+      v.to_f
+    end
+
+    meta_data do
+      {type: :number}
+    end
+  end
+
+  Paradocs.policy :string do
+    coerce do |v, k, c|
+      v.to_s
+    end
+
+    meta_data do
+      {type: :string}
+    end
+  end
+
+  Paradocs.policy :boolean do
+    coerce do |v, k, c|
+      !!v
+    end
+
+    meta_data do
+      {type: :boolean}
+    end
+  end
+
+  # type validations
+  Paradocs.policy :array do
+    message do |actual|
+      "expects an array, but got #{actual.inspect}"
+    end
+
+    validate do |value, key, payload|
+      !payload.key?(key) || value.is_a?(Array)
+    end
+
+    meta_data do
+      {type: :array}
+    end
+  end
+
+  Paradocs.policy :object do
+    message do |actual|
+      "expects a hash, but got #{actual.inspect}"
+    end
+
+    validate do |value, key, payload|
+      !payload.key?(key) ||
+        value.respond_to?(:[]) &&
+        value.respond_to?(:key?)
+    end
+
+    meta_data do
+      {type: :object}
+    end
+  end
+
+  Paradocs.policy :split do
+    coerce do |v, k, c|
+      v.kind_of?(Array) ? v : v.to_s.split(/\s*,\s*/)
+    end
+
+    meta_data do
+      {type: :array}
+    end
+  end
+
+  Paradocs.policy :datetime do
+    coerce do |v, k, c|
+      DateTime.parse(v.to_s)
+    end
+
+    meta_data do
+      {type: :datetime}
+    end
+  end
+end

data/lib/paradocs/dsl.rb

@@ -0,0 +1,68 @@
+require "paradocs"
+
+module Paradocs
+  module DSL
+    # Example
+    #   class Foo
+    #     include Paradocs::DSL
+    #
+    #     schema do
+    #       field(:title).type(:string).present
+    #       field(:age).type(:integer).default(20)
+    #     end
+    #
+    #      attr_reader :params
+    #
+    #      def initialize(input)
+    #        @params = self.class.schema.resolve(input)
+    #      end
+    #   end
+    #
+    #   foo = Foo.new(title: "A title", nope: "hello")
+    #
+    #   foo.params # => {title: "A title", age: 20}
+    #
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.schemas = {Paradocs.config.default_schema_name => Paradocs::Schema.new}
+    end
+
+    module ClassMethods
+      def schema=(sc)
+        @schemas[Paradocs.config.default_schema_name] = sc
+      end
+
+      def schemas=(sc)
+        @schemas = sc
+      end
+
+      def inherited(subclass)
+        subclass.schemas = @schemas.each_with_object({}) do |(key, sc), hash|
+          hash[key] = sc.merge(Paradocs::Schema.new)
+        end
+      end
+
+      def schema(*args, &block)
+        options = args.last.is_a?(Hash) ? args.last : {}
+        key = args.first.is_a?(Symbol) ? args.shift : Paradocs.config.default_schema_name
+        current_schema = @schemas.fetch(key) { Paradocs::Schema.new }
+        new_schema = if block_given? || options.any?
+          Paradocs::Schema.new(options, &block)
+        elsif args.first.is_a?(Paradocs::Schema)
+          args.first
+        end
+
+        return current_schema unless new_schema
+
+        @schemas[key] = current_schema ? current_schema.merge(new_schema) : new_schema
+        paradocs_after_define_schema(@schemas[key])
+        @schemas[key]
+      end
+
+      def paradocs_after_define_schema(sc)
+        # noop hook
+      end
+    end
+  end
+end

data/lib/paradocs/extensions/insides.rb

@@ -0,0 +1,77 @@
+module Paradocs
+  module Extensions
+    module Insides
+      def structure(ignore_transparent: true, root: "", &block)
+        flush!
+        fields.each_with_object({meta_keys[:errors] => [], meta_keys[:subschemes] => {}}) do |(_, field), obj|
+          meta, sc = collect_meta(field, root)
+          if sc
+            meta[:structure] = sc.structure(ignore_transparent: ignore_transparent, root: meta[:json_path], &block)
+            obj[meta_keys[:errors]] += meta[:structure].delete(meta_keys[:errors])
+          else
+            obj[meta_keys[:errors]] += field.possible_errors
+          end
+          obj[field.key] = meta unless ignore_transparent && field.transparent?
+          yield(field.key, meta) if block_given?
+
+          next unless field.mutates_schema?
+          subschemes.each do |name, subschema|
+            obj[meta_keys[:subschemes]][name] = subschema.structure(ignore_transparent: ignore_transparent, root: root, &block)
+            obj[meta_keys[:errors]] += obj[meta_keys[:subschemes]][name][meta_keys[:errors]]
+          end
+        end
+      end
+
+      def flatten_structure(ignore_transparent: true, root: "", &block)
+        flush!
+        fields.each_with_object({meta_keys[:errors] => [], meta_keys[:subschemes] => {}}) do |(_, field), obj|
+          meta, sc = collect_meta(field, root)
+          humanized_name = meta.delete(:nested_name)
+          obj[humanized_name] = meta unless ignore_transparent && field.transparent?
+
+          if sc
+            deep_result = sc.flatten_structure(ignore_transparent: ignore_transparent, root: meta[:json_path], &block)
+            obj[meta_keys[:errors]] += deep_result.delete(meta_keys[:errors])
+            obj[meta_keys[:subschemes]].merge!(deep_result.delete(meta_keys[:subschemes]))
+            obj.merge!(deep_result)
+          else
+            obj[meta_keys[:errors]] += field.possible_errors
+          end
+          yield(humanized_name, meta) if block_given?
+          next unless field.mutates_schema?
+          subschemes.each do |name, subschema|
+            obj[meta_keys[:subschemes]][name] ||= subschema.flatten_structure(ignore_transparent: ignore_transparent, root: root, &block)
+            obj[meta_keys[:errors]] += obj[meta_keys[:subschemes]][name][meta_keys[:errors]]
+          end
+        end
+      end
+
+      def walk(meta_key = nil, &visitor)
+        r = visit(meta_key, &visitor)
+        Results.new(r, {}, {})
+      end
+
+      def visit(meta_key = nil, &visitor)
+        fields.each_with_object({}) do |(_, field), m|
+          m[field.key] = field.visit(meta_key, &visitor)
+        end
+      end
+
+      private
+
+      def collect_meta(field, root)
+        json_path = root.empty? ? "$.#{field.key}" : "#{root}.#{field.key}"
+        meta = field.meta_data.merge(json_path: json_path)
+        sc = meta.delete(:schema)
+        meta[:mutates_schema] = true if meta.delete(:mutates_schema)
+        json_path << "[]" if meta[:type] == :array
+        meta[:nested_name] = json_path.gsub("[]", "")[2..-1]
+        [meta, sc]
+      end
+
+      def meta_keys
+        %i(errors subschemes).map! { |key| [key, "#{Paradocs.config.meta_prefix}#{key}".to_sym] }.to_h
+      end
+    end
+  end
+end

data/lib/paradocs/field.rb

@@ -0,0 +1,152 @@
+require "paradocs/field_dsl"
+
+module Paradocs
+  class Field
+    include FieldDSL
+
+    attr_reader :key, :meta_data
+    Result = Struct.new(:eligible?, :value)
+
+    def initialize(key)
+      @key = key
+      @policies = []
+      @default_block = nil
+      @meta_data = {}
+      @policies = []
+      @mutation_block = nil
+      @expects_mutation = nil
+    end
+
+    def meta(hash = nil)
+      @meta_data = @meta_data.merge(hash) if hash.is_a?(Hash)
+      self
+    end
+
+    def possible_errors
+      meta_data.map { |_, v| v[:errors] if v.is_a?(Hash) }.flatten.compact
+    end
+
+    def default(value)
+      meta default: value
+      @default_block = (value.respond_to?(:call) ? value : ->(key, payload, context) { value })
+      self
+    end
+
+    def mutates_schema!(&block)
+      @mutation_block   ||= block if block_given?
+      @expects_mutation = @expects_mutation.nil? && true
+      meta mutates_schema: @mutation_block
+      @mutation_block
+    end
+
+    def mutates_schema?
+      !!@mutation_block
+    end
+
+    def expects_mutation?
+      mutates_schema? && @expects_mutation
+    end
+
+    def policy(key, *args)
+      pol = lookup(key, args)
+
+      meta pol.meta_data
+      policies << pol
+      self
+    end
+
+    alias_method :type, :policy
+    alias_method :rule, :policy
+
+    def schema(sc = nil, &block)
+      sc = (sc ? sc : Schema.new(&block))
+      meta schema: sc
+      policy sc.schema
+    end
+
+    def transparent?
+      !!meta_data[:transparent]
+    end
+
+    def visit(meta_key = nil, &visitor)
+      if sc = meta_data[:schema]
+        r = sc.visit(meta_key, &visitor)
+        (meta_data[:type] == :array) ? [r] : r
+      else
+        meta_key ? meta_data[meta_key] : yield(self)
+      end
+    end
+
+    def subschema_for_mutation(payload, env)
+      subschema_name = @mutation_block.call(payload[key], key, payload, env) if @mutation_block
+      @expects_mutation = false
+      subschema_name
+    end
+
+    def resolve(payload, context)
+      eligible = payload.key?(key)
+      value = payload[key] # might be nil
+
+      if !eligible && has_default?
+        eligible = true
+        value = default_block.call(key, payload, context)
+        payload[key] = value
+      end
+      policies.each do |policy|
+        # pass schema additional data to the each policy
+        policy.environment = context.environment if policy.respond_to?(:environment=)
+        if !policy.eligible?(value, key, payload)
+          eligible = false
+          if has_default?
+            eligible = true
+            value = default_block.call(key, payload, context)
+          end
+          break
+        else
+          value, valid = resolve_one(policy, value, payload, context)
+
+          unless valid
+            eligible = true # eligible, but has errors
+            break # only one error at a time
+          end
+        end
+      end
+
+      Result.new(eligible, value)
+    end
+
+    private
+    attr_reader :policies, :default_block
+
+    def resolve_one(policy, value, payload, context)
+      begin
+        value = policy.coerce(value, key, context)
+        valid = policy.valid?(value, key, payload)
+
+        context.add_error(policy.message) unless valid
+        [value, valid]
+      rescue *(policy.try(:errors) || []) => e
+        # context.add_error e.message # NOTE: do we need it?
+        raise e
+      rescue *(policy.try(:silent_errors) || []) => e
+        context.add_error e.message
+      rescue StandardError => e
+        raise e if policy.is_a? Paradocs::Schema # from the inner level, just reraise
+        raise ConfigurationError.new("#{e.class} should be registered in the policy") if Paradocs.config.explicit_errors
+        context.add_error policy.message unless Paradocs.config.explicit_errors
+        [value, false]
+      end
+    end
+
+    def has_default?
+      !!default_block
+    end
+
+    def lookup(key, args)
+      obj = key.is_a?(Symbol) ? Paradocs.registry.policies[key] : key
+
+      raise ConfigurationError, "No policies defined for #{key.inspect}" unless obj
+      obj.respond_to?(:new) ? obj.new(*args) : obj
+    end
+  end
+end

data/lib/paradocs/field_dsl.rb

@@ -0,0 +1,36 @@
+module Paradocs
+  # Field DSL
+  # host instance must implement:
+  # #meta(options Hash)
+  # #policy(key Symbol) self
+  #
+  module FieldDSL
+    def required
+      policy :required
+    end
+
+    def present
+      required.policy :present
+    end
+
+    def declared
+      policy :declared
+    end
+
+    def options(opts)
+      policy :options, opts
+    end
+
+    def whitelisted
+      policy :whitelisted
+    end
+
+    def transparent
+      meta transparent: true
+    end
+
+    def length(opts)
+      policy :length, opts
+    end
+  end
+end