paradocs 1.0.24 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b3362dbf83838f9f786222294f5438ed7d24bfc
-  data.tar.gz: 3ac665829a9993b65f21a15d95b71e874e1029db
+  metadata.gz: 0df2185fac7b1e70254c9531622e135c6609f309
+  data.tar.gz: 701ec92673e9044bc8a8384e251276aa7863d37e
 SHA512:
-  metadata.gz: 38a9d697a211fd51f1e92bb289de5e7397971141188c15093880033cec1fee862d2bc3a1be00b0ac81b19dd97598e60e4f4e1e6d6aaa7222809fcd11850dc170
-  data.tar.gz: 2834c21794d059e1d1dbb48b09dceacf9379bceb83199709b8d56d92a91a36410418681ed5b0b815272bd51b5dcbc84e7b6a678f4876eb1441f0efdc9bad0af2
+  metadata.gz: aa14905a01be3d1d54589aabc53fbc2f14d3a17352742a9eece1e76b324f146d94f5860ae4f59d738007e809c1fb0eb3ae95579d2a8237798e80a7a6f43ff2b9
+  data.tar.gz: 0c5fedee64178f630d403db573b2d8a4e2e4bc44b88e65df636c88aa1d9857836267d77ed34a1236036ff97bb105e37252f4948d46fcdc600850e682a5db082d

data/.readthedocs.yml

@@ -0,0 +1,5 @@
+version: 2
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false

data/docs/custom_configuration.md

@@ -0,0 +1,10 @@
+# Configuration
+```rb
+Paradocs.configure do |config|
+  config.explicit_errors = false       # set to true if you want all errors from the policies to be explicitly registered in the policy
+  config.whitelisted_keys = []         # enrich it with global white-listed keys if you use WhiteList feature
+  config.default_schema_name = :schema # this name will be set for unnamed schemas
+  config.meta_prefix = "_"             # used in #structure and #flatten_structure methods. All the metadata will be prefixed with this prefix.
+  config.whitelist_coercion = nil      # set up a Proc here, that receives |value, field.meta| for each whitelisted field in order to enrich the whitelisting logic.
+end
+```

data/docs/documentation_generation.md

@@ -0,0 +1,291 @@
+# Documentation Generation
+
+A `Schema` instance has a `#structure` method that return `Paradocs::Extensions::Structure` instance that allows instrospecting schema meta data.
+
+It's supposed to have the following schema:
+```ruby
+schema = Paradocs::Schema.new do
+  field(:data).type(:object).present.schema do
+    field(:id).type(:integer).present.policy(:policy_with_error)
+    field(:name).type(:string).meta(label: "very important staff")
+    field(:role).type(:string).declared.options(["admin", "user"]).default("user").mutates_schema! do |*|
+      :test_subschema
+    end
+    field(:extra).type(:array).required.schema do
+      field(:extra).declared.default(false).policy(:policy_with_silent_error)
+    end
+
+    mutation_by!(:name) { :subschema }
+
+    subschema(:subschema) do
+      field(:test_field).present
+    end
+    subschema(:test_subschema) do
+      field(:test1).present
+    end
+  end
+end
+```
+
+## Structure#nested
+> This method returns schema structure in a nested way including subschemes.
+```ruby
+schema.structure.nested.to_json # =>
+{
+  "_errors": ["ArgumentError"],
+  "_subschemes": {},
+  "data": {
+    "type": "object",
+    "required": true,
+    "present": true,
+    "json_path": "$.data",
+    "nested_name": "data",
+    "structure": {
+      "_subschemes": {
+        "subschema": {
+          "_errors": [],
+          "_subschemes": {},
+          "test_field": {
+            "required": true,
+            "present": true,
+            "json_path": "$.data.test_field",
+            "nested_name": "data.test_field"
+          }
+        },
+        "test_subschema": {
+          "_errors": [],
+          "_subschemes": {},
+          "test1": {
+            "required": true,
+            "present": true,
+            "json_path": "$.data.test1",
+            "nested_name": "data.test1"
+          }
+        }
+      },
+      "id": {
+        "type": "integer",
+        "required": true,
+        "present": true,
+        "policy_with_error": {"errors": ["ArgumentError"]},
+        "json_path": "$.data.id",
+        "nested_name": "data.id"
+      },
+      "name": {
+        "type": "string",
+        "label": "very important staff",
+        "json_path": "$.data.name",
+        "mutates_schema": true,
+        "nested_name": "data.name"
+      },
+      "role": {
+        "type": "string",
+        "options": ["admin", "user"],
+        "default": "user",
+        "json_path": "$.data.role",
+        "mutates_schema": true,
+        "nested_name": "data.role"
+      },
+      "extra": {
+        "type": "array",
+        "required": true,
+        "json_path": "$.data.extra[]",
+        "nested_name": "data.extra",
+        "structure": {
+          "_subschemes": {},
+          "extra": {
+            "default": false,
+            "policy_with_silent_error": {"errors": []},
+            "json_path": "$.data.extra[].extra",
+            "nested_name": "data.extra.extra"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Structure#flatten
+> This method returns schema structure in a flatten (without deep nesting) way including subschemes.
+```rb
+schema.structure.flatten.to_json # =>
+{
+  "_errors": ["ArgumentError"],
+  "_subschemes": {
+    "subschema": {
+      "_errors": [],
+      "_subschemes": {},
+      "data.test_field": {
+        "required": true,
+        "present": true,
+        "json_path": "$.data.test_field"
+      }
+    },
+    "test_subschema": {
+      "_errors": [],
+      "_subschemes": {},
+      "data.test1": {
+        "required": true,
+        "present": true,
+        "json_path": "$.data.test1"
+      }
+    }
+  },
+  "data": {
+    "type": "object",
+    "required": true,
+    "present": true,
+    "json_path": "$.data"
+  },
+  "data.id": {
+    "type": "integer",
+    "required": true,
+    "present": true,
+    "policy_with_error": {"errors": ["ArgumentError"]},
+    "json_path": "$.data.id"
+  },
+  "data.name": {
+    "type": "string",
+    "label": "very important staff",
+    "json_path": "$.data.name",
+    "mutates_schema": true
+  },
+  "data.role": {
+    "type": "string",
+    "options": ["admin", "user"],
+    "default": "user",
+    "json_path": "$.data.role",
+    "mutates_schema": true
+  },
+  "data.extra": {
+    "type": "array",
+    "required": true,
+    "json_path": "$.data.extra[]"
+  },
+  "data.extra.extra": {
+    "default": false,
+    "policy_with_silent_error": {"errors": []},
+    "json_path": "$.data.extra[].extra"
+  }
+}
+```
+
+
+## Structure#all_nested
+
+> This method returns all available combinations of schema (built on subschemas) saving the nesting.
+
+Will return a hash with 2 structures named by the names of declared subschemas:
+```rb
+all_nested = schema.structure.all_nested
+all_nested.keys # => [:subschema, :test_subschema]
+all_nested[:subschema] # =>
+{
+  _errors: [],
+  "data" => {
+    type:      :object,
+    required:  true,
+    present:   true,
+    json_path: "$.data",
+    structure: {
+      "role"       => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+      "extra"      => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
+      "test_field" => {required: true, present: true, json_path: "$.data.test_field"},
+      "id"         => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+      "name"       => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+    }
+  }
+}
+all_nested[:test_subschema] # =>
+{
+  _errors:     [],
+  "data" => {
+    type:      :object,
+    required:  true,
+    present:   true,
+    json_path: "$.data",
+    structure: {
+      "role"  => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+      "extra" => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
+      "test1" => {required: true, present: true, json_path: "$.data.test1"},
+      "id"    => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+      "name"  => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+    }
+  }
+}
+```
+
+## Structure#all_flatten
+> This method returns all available combinations of schema (built on subschema) without nesting (the same way as Structure#flatten method does)
+
+Schema is the same as described in Structure#all_nested
+```rb
+schema.structure.all_flatten # =>
+{
+  subschema: {
+    _errors: [],
+    "data"             => {type: :object, required: true, present: true, json_path: "$.data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"},
+    "data.test_field"  => {required: true, present: true, json_path: "$.data.test_field"}
+  },
+  test_subschema: {
+    _errors: [],
+    "data"             => {type: :object, required: true, present: true, json_path: "$.data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"},
+    "data.test1"       => {required: true, present: true, json_path: "$.data.test1"}
+  }
+}
+```
+
+## Schema#walk
+
+The `#walk` method can recursively walk a schema definition and extract meta data or field attributes.
+
+```ruby
+schema_documentation = create_user_schema.walk do |field|
+  {type: field.meta_data[:type], label: field.meta_data[:label]}
+end.output
+
+# Returns
+
+{
+  name: {type: :string, label: "User's full name"},
+  age: {type: :integer, label: "User's age"},
+  status: {type: :string, label: nil},
+  friends: [
+    {
+      name: {type: :string, label: "Friend full name"},
+      email: {type: nil, label: "Friend email"}
+    }
+  ]
+}
+```
+
+When passed a _symbol_, it will collect that key from field meta data.
+
+```ruby
+schema_labels = create_user_schema.walk(:label).output
+
+# returns
+
+{
+  name: "User's full name",
+  age: "User's age",
+  status: nil,
+  friends: [
+    {name: "Friend full name", email: "Friend email"}
+  ]
+}
+```
+
+Potential uses for this are generating documentation (HTML, or [JSON Schema](http://json-schema.org/), [Swagger](http://swagger.io/), or maybe even mock API endpoints with example data.
+

data/docs/faq.md

@@ -0,0 +1,21 @@
+# FAQ
+## Defaults
+### Q: I need the child schema to be enriched with the specified defaults is parent key is absent.
+```rb
+schema do
+  field(:top_level).type(:string).required.default('top_level')
+  field(:nested).type(:object).required.schema do
+    field(:start_date).type(:datetime).required.default(->(a,b,c) { Time.now })
+    field(:ends_after).type(:integer).required.default(5)
+  end
+end
+# usage
+TestSchema.schema.resolve({}).output # => {:top_level=>"top_level", :nested=>nil, :configurations=>nil}
+TestSchema.schema.resolve({nested: {}}).output # => {:top_level=>"top_level", :nested=>{:start_date=>#<DateTime: 2020-08-31T15:36:43+02:00 ((2459093j,49003s,0n),+7200s,2299161j)>, :ends_after=>5}, :configurations=>nil}
+# I want resolving on {} to include the :nested structure.
+```
+
+### A: Set `.default({})` to your `:nested` field.
+> Fields from nested schema are invoked only when the object for the schema exists.
+
+

data/docs/form_objects_dsl.md

@@ -0,0 +1,90 @@
+# Form objects DSL
+
+## DSL
+You can use schemas and fields on their own, or include the `DSL` module in your own classes to define form objects.
+
+```ruby
+require "parametric/dsl"
+
+class CreateUserForm
+  include Paradocs::DSL
+
+  schema(:test) do
+    field(:name).type(:string).required
+    field(:email).policy(:email).required
+    field(:age).type(:integer)
+    subschema_by(:age) { |age| age > 18 ? :allow : :deny }
+  end
+
+  subschema_for(:test, name: :allow) { field(:role).options(["sign_in"]) }
+  subschema_for(:test, name: :deny) { field(:role).options([]) }
+
+  attr_reader :params, :errors
+
+  def initialize(input_data)
+    results = self.class.schema.resolve(input_data)
+    @params = results.output
+    @errors = results.errors
+  end
+
+  def run!
+    if !valid?
+      raise InvalidFormError.new(errors)
+    end
+
+    run
+  end
+
+  def valid?
+    !errors.any?
+  end
+
+  private
+
+  def run
+    User.create!(params)
+  end
+end
+```
+
+Form schemas can also be defined by passing another form or schema instance. This can be useful when building form classes in runtime.
+
+```ruby
+UserSchema = Paradocs::Schema.new do
+  field(:name).type(:string).present
+  field(:age).type(:integer)
+end
+
+class CreateUserForm
+  include Paradocs::DSL
+  # copy from UserSchema
+  schema UserSchema
+end
+```
+
+## Form object inheritance
+
+Sub classes of classes using the DSL will inherit schemas defined on the parent class.
+
+```ruby
+class UpdateUserForm < CreateUserForm
+  # All field definitions in the parent are conserved.
+  # New fields can be defined
+  # or existing fields overriden
+  schema do
+    # make this field optional
+    field(:name).declared.present
+  end
+
+  def initialize(user, input_data)
+    super input_data
+    @user = user
+  end
+
+  private
+  def run
+    @user.update params
+  end
+end
+```
+

data/docs/index.md

@@ -0,0 +1,106 @@
+# Getting Started
+## Introduction
+> [Paradocs](https://github.com/mtkachenk0/paradocs) = Extended [Parametric gem](https://github.com/ismasan/parametric) + Documentation Generation
+
+![Ruby](https://github.com/mtkachenk0/paradocs/workflows/Ruby/badge.svg)
+
+Declaratively define data schemas in your Ruby objects, and use them to whitelist, validate or transform inputs to your programs.
+
+Useful for building self-documeting APIs, search or form objects. Or possibly as an alternative to Rails' _strong parameters_ (it has no dependencies on Rails and can be used stand-alone).
+## Installation
+```sh
+$ gem install paradocs
+```
+
+Or with Bundler in your Gemfile.
+```rb
+gem 'paradocs'
+```
+
+## Try it out
+
+Define a schema
+
+```ruby
+schema = Paradocs::Schema.new do
+  field(:title).type(:string).present
+  field(:status).options(["draft", "published"]).default("draft")
+  field(:tags).type(:array)
+end
+```
+
+Populate and use. Missing keys return defaults, if provided.
+
+```ruby
+form = schema.resolve(title: "A new blog post", tags: ["tech"])
+
+form.output # => {title: "A new blog post", tags: ["tech"], status: "draft"}
+form.errors # => {}
+```
+
+Undeclared keys are ignored.
+
+```ruby
+form = schema.resolve(foobar: "BARFOO", title: "A new blog post", tags: ["tech"])
+
+form.output # => {title: "A new blog post", tags: ["tech"], status: "draft"}
+```
+
+Validations are run and errors returned
+
+
+```ruby
+form = schema.resolve({})
+form.errors # => {"$.title" => ["is required"]}
+```
+
+If options are defined, it validates that value is in options
+
+```ruby
+form = schema.resolve({title: "A new blog post", status: "foobar"})
+form.errors # => {"$.status" => ["expected one of draft, published but got foobar"]}
+```
+
+## Nested schemas
+
+A schema can have nested schemas, for example for defining complex forms.
+
+```ruby
+person_schema = Paradocs::Schema.new do
+  field(:name).type(:string).required
+  field(:age).type(:integer)
+  field(:friends).type(:array).schema do
+    field(:name).type(:string).required
+    field(:email).policy(:email)
+  end
+end
+```
+
+It works as expected
+
+```ruby
+results = person_schema.resolve(
+  name: "Joe",
+  age: "38",
+  friends: [
+    {name: "Jane", email: "jane@email.com"}
+  ]
+)
+
+results.output # => {name: "Joe", age: 38, friends: [{name: "Jane", email: "jane@email.com"}]}
+```
+
+Validation errors use [JSON path](http://goessner.net/articles/JsonPath/) expressions to describe errors in nested structures
+
+```ruby
+results = person_schema.resolve(
+  name: "Joe",
+  age: "38",
+  friends: [
+    {email: "jane@email.com"}
+  ]
+)
+
+results.errors # => {"$.friends[0].name" => "is required"}
+```
+