paradocs 1.0.24 → 1.1.0

data/docs/struct.md

@@ -0,0 +1,135 @@
+# Structs
+## Overview
+Structs turn schema definitions into objects graphs with attribute readers.
+
+Add optional `Paradocs::Struct` module to define struct-like objects with schema definitions.
+
+```ruby
+require 'parametric/struct'
+
+class User
+  include Paradocs::Struct
+
+  schema do
+    field(:name).type(:string).present
+    field(:friends).type(:array).schema do
+      field(:name).type(:string).present
+      field(:age).type(:integer)
+    end
+  end
+end
+```
+
+`User` objects can be instantiated with hash data, which will be coerced and validated as per the schema definition.
+
+```ruby
+user = User.new(
+  name: 'Joe',
+  friends: [
+    {name: 'Jane', age: 40},
+    {name: 'John', age: 30},
+  ]
+)
+
+# properties
+user.name # => 'Joe'
+user.friends.first.name # => 'Jane'
+user.friends.last.age # => 30
+```
+
+## Errors
+
+Both the top-level and nested instances contain error information:
+
+```ruby
+user = User.new(
+  name: '', # invalid
+  friends: [
+    # friend name also invalid
+    {name: '', age: 40},
+  ]
+)
+
+user.valid? # false
+user.errors['$.name'] # => "is required and must be present"
+user.errors['$.friends[0].name'] # => "is required and must be present"
+
+# also access error in nested instances directly
+user.friends.first.valid? # false
+user.friends.first.errors['$.name'] # "is required and must be valid"
+```
+
+## .new!(hash)
+
+Instantiating structs with `.new!(hash)` will raise a `Paradocs::InvalidStructError` exception if the data is validations fail. It will return the struct instance otherwise.
+
+`Paradocs::InvalidStructError` includes an `#errors` property to inspect the errors raised.
+
+```ruby
+begin
+  user = User.new!(name: '')
+rescue Paradocs::InvalidStructError => e
+  e.errors['$.name'] # "is required and must be present"
+end
+```
+
+## Nested structs
+
+You can also pass separate struct classes in a nested schema definition.
+
+```ruby
+class Friend
+  include Paradocs::Struct
+
+  schema do
+    field(:name).type(:string).present
+    field(:age).type(:integer)
+  end
+end
+
+class User
+  include Paradocs::Struct
+
+  schema do
+    field(:name).type(:string).present
+    # here we use the Friend class
+    field(:friends).type(:array).schema Friend
+  end
+end
+```
+
+## Inheritance
+
+Struct subclasses can add to inherited schemas, or override fields defined in the parent.
+
+```ruby
+class AdminUser < User
+  # inherits User schema, and can add stuff to its own schema
+  schema do
+    field(:permissions).type(:array)
+  end
+end
+```
+
+## #to_h
+
+`Struct#to_h` returns the ouput hash, with values coerced and any defaults populated.
+
+```ruby
+class User
+  include Paradocs::Struct
+  schema do
+    field(:name).type(:string)
+    field(:age).type(:integer).default(30)
+  end
+end
+
+user = User.new(name: "Joe")
+user.to_h # {name: "Joe", age: 30}
+```
+
+## Struct equality
+
+`Paradocs::Struct` implements `#==()` to compare two structs Hash representation (same as `struct1.to_h.eql?(struct2.to_h)`.
+
+Users can override `#==()` in their own classes to do whatever they need.

data/docs/subschema.md

@@ -0,0 +1,29 @@
+# Subchemas
+> When your schema can change on-the-fly.
+
+## Subschemas and mutations.
+Sometimes depending on the data the structure may vary. Most frequently used option is to use `:declared` policy (a.k.a. conditional, but below is another option:
+
+- Mutations are blocks that are assigned to a field and called during the validation (in #resolve), block receives all the related data and should return a subschema name.
+- Subschemas are conditional schemas declared inside schemas. They doesn't exist until mutation block is called and decides to invoke a subschema.
+```ruby
+person_schema = Paradocs::Schema.new do
+  field(:role).type(:string).options(["admin", "user"]).mutates_schema! do |value, key, payload, env|
+    value == :admin ? :admin_schema : :user_schema
+  end
+
+  subschema(:admin_schema) do
+    field(:permissions).present.type(:string).options(["superuser"])
+    field(:admin_field)
+  end
+  subschema(:user_schema) do
+    field(:permissions).present.type(:string).options(["readonly"])
+    field(:user_field)
+  end
+end
+
+results = person_schema.resolve(name: "John", age: 20, role: :admin, permissions: "superuser")
+results.output # => {name: "John", age: 20, role: :admin, permissions: "superuser", admin_field: nil}
+results = person_schema.resolve(name: "John", age: 20, role: :admin, permissions: "readonly")
+results.errors => {"$.permissions"=>["must be one of superuser, but got readonly"]}
+```

data/lib/paradocs/extensions/payload_builder.rb

@@ -0,0 +1,43 @@
+module Paradocs
+  module Extensions
+    class PayloadBuilder
+      attr_reader :structure, :result
+      attr_accessor :skip_word
+      def initialize(schema, skip_word: :skip)
+        @structure  = schema.structure
+        @skip_word  = skip_word
+      end
+
+      def build!(&block)
+        structure.all_nested.map { |name, struct| [name, build_simple_structure(struct, &block)] }.to_h
+      end
+
+      private
+
+      def build_simple_structure(struct, &block)
+        struct.map do |key, value|
+          key = key.to_s
+          next if key.start_with?(Paradocs.config.meta_prefix) # skip all the meta fields
+          ex_value = restore_one(key, value, &block)
+          next if ex_value == @skip_word
+          [key, ex_value]
+        end.compact.to_h
+      end
+
+      def restore_one(key, value, &block)
+        default = value[:default]
+        ex_value = if value[:structure]
+          data = build_simple_structure(value[:structure], &block)
+          value[:type] == :array ? [data] : data
+        elsif default
+          default.is_a?(Proc) ? default.call : default
+        elsif value[:options] && !value[:options].empty?
+          options = value[:options]
+          value[:type] == :array ? options : options.sample
+        end
+        return ex_value unless block_given?
+        yield(key, value, ex_value, @skip_word)
+      end
+    end
+  end
+end

data/lib/paradocs/extensions/structure.rb

@@ -0,0 +1,118 @@
+module Paradocs
+  module Extensions
+    class Structure
+      DEFAULT = :generic
+      %w(errors subschemes).each do |key|
+        define_method(key) { "#{Paradocs.config.meta_prefix}#{key}".to_sym }
+      end
+
+      attr_reader :schema, :ignore_transparent, :root
+      attr_accessor :ignore_transparent
+      def initialize(schema, ignore_transparent=true, root="")
+        @schema             = schema
+        @ignore_transparent = ignore_transparent
+        @root               = root
+      end
+
+      def flush!
+        @nested, @all_nested, @flatten, @all_flatten = [nil] * 4
+      end
+
+      def nested(&block)
+        @nested ||= schema.fields.each_with_object({errors => [], subschemes => {}}) do |(_, field), result|
+          meta, sc = collect_meta(field, root)
+          if sc
+            meta[:structure] = self.class.new(sc, ignore_transparent, meta[:json_path]).nested(&block)
+            result[errors] += meta[:structure].delete(errors)
+          else
+            result[errors] += field.possible_errors
+          end
+          result[field.key] = meta unless ignore_transparent && field.transparent?
+          yield(field.key, meta) if block_given?
+
+          next unless field.mutates_schema?
+          schema.subschemes.each do |name, subschema|
+            result[subschemes][name] = self.class.new(subschema, ignore_transparent, root).nested(&block)
+            result[errors] += result[subschemes][name][errors]
+          end
+        end
+      end
+
+      def all_nested(&block)
+        @all_nested ||= all_flatten(&block).each_with_object({}) do |(name, struct), obj|
+          obj[name] = {}
+          # sort the flatten struct to have iterated 1lvl keys before 2lvl and so on...
+          struct.sort_by { |k, v| k.to_s.count(".") }.each do |key, value|
+            target = obj[name]
+            key, value = key.to_s, value.clone # clone the values, because we do mutation below
+            next target[key.to_sym] = value if key.start_with?(Paradocs.config.meta_prefix) # copy meta fields
+
+            parts = key.split(".")
+            next target[key] ||= value if parts.size == 1 # copy 1lvl key
+            parts.each.with_index do |subkey, index|
+              target[subkey] ||= value
+              next if parts.size == index + 1
+              target[subkey][:structure] ||= {}
+              target = target[subkey][:structure] # target goes deeper for each part
+            end
+          end
+        end
+      end
+
+      def all_flatten(schema_structure=nil, &block)
+        return @all_flatten if @all_flatten
+        schema_structure ||= flatten(&block)
+        if schema_structure[subschemes].empty?
+          schema_structure.delete(subschemes) # don't include redundant key
+          return @all_flatten = {DEFAULT => schema_structure}
+        end
+        @all_flatten = schema_structure[subschemes].each_with_object({}) do |(name, subschema), result|
+          if subschema[subschemes].empty?
+             result[name] = schema_structure.merge(subschema)
+             result[name].delete(subschemes)
+             next result[name]
+          end
+
+          all_flatten(subschema).each do |sub_name, schema|
+            result["#{name}_#{sub_name}".to_sym] = schema_structure.merge(schema)
+          end
+        end
+      end
+
+      def flatten(&block)
+        @flatten ||= schema.fields.each_with_object({errors => [], 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 = self.class.new(sc, ignore_transparent, meta[:json_path]).flatten(&block)
+            obj[errors] += deep_result.delete(errors)
+            obj[subschemes].merge!(deep_result.delete(subschemes))
+            obj.merge!(deep_result)
+          else
+            obj[errors] += field.possible_errors
+          end
+          yield(humanized_name, meta) if block_given?
+          next unless field.mutates_schema?
+          schema.subschemes.each do |name, subschema|
+            obj[subschemes][name] ||= self.class.new(subschema, ignore_transparent, root).flatten(&block)
+            obj[errors] += obj[subschemes][name][errors]
+          end
+        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
+    end
+  end
+end

data/lib/paradocs/schema.rb

@@ -1,14 +1,13 @@
 require "paradocs/context"
 require "paradocs/results"
 require "paradocs/field"
-require "paradocs/extensions/insides"
+require "paradocs/extensions/structure"
+require "paradocs/extensions/payload_builder"
 
 module Paradocs
   class Schema
-    include Extensions::Insides
-
     attr_accessor :environment
-    attr_reader :subschemes
+    attr_reader :subschemes, :structure_builder
     def initialize(options={}, &block)
       @options = options
       @fields = {}
@@ -18,6 +17,7 @@ module Paradocs
       @default_field_policies = []
       @ignored_field_keys = []
       @expansions = {}
+      @structure_builder = Paradocs::Extensions::Structure.new(self)
     end
 
     def schema
@@ -29,6 +29,27 @@ module Paradocs
       f.mutates_schema!(&block)
     end
 
+    def structure(ignore_transparent: true)
+      flush!
+      structure_builder.ignore_transparent = ignore_transparent
+      structure_builder
+    end
+
+    def example_payloads(&block)
+      @example_payloads ||= Paradocs::Extensions::PayloadBuilder.new(self).build!(&block)
+    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
+
     def subschema(*args, &block)
       options = args.last.is_a?(Hash) ? args.last : {}
       name = args.first.is_a?(Symbol) ? args.shift : Paradocs.config.default_schema_name
@@ -143,6 +164,11 @@ module Paradocs
       end
     end
 
+    def flush!
+      @fields = {}
+      @applied = false
+    end
+
     protected
 
     attr_reader :definitions, :options
@@ -205,10 +231,5 @@ module Paradocs
       end
       @applied = true
     end
-
-    def flush!
-      @fields = {}
-      @applied = false
-    end
   end
 end

data/lib/paradocs/version.rb

@@ -1,3 +1,3 @@
 module Paradocs
-  VERSION = "1.0.24"
+  VERSION = "1.1.0"
 end

data/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: Paradocs
+theme:
+    name: readthedocs
+    nav_style: dark
+nav:
+  - 'index.md'
+  - 'policies.md'
+  - 'schema.md'
+  - 'struct.md'
+  - 'form_objects_dsl.md'
+  - 'subschema.md'
+  - 'documentation_generation.md'
+  - 'payload_builder.md'
+  - 'custom_configuration.md'
+  - 'faq.md'
+

data/paradocs.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["tkachenko.maxim.w@gmail.com", "ismaelct@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.homepage      = "https://paradocs.readthedocs.io/en/latest"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 2.1"
-  spec.add_development_dependency "rake", ">= 12.3.3"
+  spec.add_development_dependency "rake", '~> 12.3'
   spec.add_development_dependency "rspec", '3.4.0'
   spec.add_development_dependency "pry", "~> 0"
 end

data/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.1.2