paradocs 1.0.24 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b3362dbf83838f9f786222294f5438ed7d24bfc
-  data.tar.gz: 3ac665829a9993b65f21a15d95b71e874e1029db
+  metadata.gz: c9ed12715c0df054876f622c3dada9cc4a2d8fd5
+  data.tar.gz: bfe8c1cb2eb4aa9f15eb08349425611deccb3517
 SHA512:
-  metadata.gz: 38a9d697a211fd51f1e92bb289de5e7397971141188c15093880033cec1fee862d2bc3a1be00b0ac81b19dd97598e60e4f4e1e6d6aaa7222809fcd11850dc170
-  data.tar.gz: 2834c21794d059e1d1dbb48b09dceacf9379bceb83199709b8d56d92a91a36410418681ed5b0b815272bd51b5dcbc84e7b6a678f4876eb1441f0efdc9bad0af2
+  metadata.gz: b9d827bf00b03d7766600e438d8ee16a9938ab099cd807d0d236cfb37758d104d76f26fdf713c7f39c550ce65df56c30b4dcfbeedb5fa7c5ebc93fa67c66199d
+  data.tar.gz: c4ac5998e89948246c01b6ec04d39ce5332c66da32902ac2b63a06672746dc002a91dc013372bc4cb33410a72e15c1de85bfb08aab8a17659dc9da84f4c793b5

data/.readthedocs.yml

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

data/README.md

@@ -37,14 +37,4 @@ form.errors # => {}
 ```
 
 ## Learn more
-- [Getting Started](https://github.com/mtkachenk0/paradocs/wiki/Getting-Started)
-- [Built In Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#built-in-policies)
-	- [Type Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#type-coercions)
-	- [Presence Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#presence-policies)
-  - [Custom Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#custom-policies)
-- [Schema](https://github.com/mtkachenk0/paradocs/wiki/schema)
-	- [Expanding fields dynamically](https://github.com/mtkachenk0/paradocs/wiki/schema#expanding-fields-dynamically)
-	- [Multiple schema definitions](https://github.com/mtkachenk0/paradocs/wiki/schema#multiple-schema-definitions)
-- [Documentation Generation](https://github.com/mtkachenk0/paradocs/wiki/Documentation-Generation)
-- [What if my fields are conditional?!](https://github.com/mtkachenk0/paradocs/wiki/subschema)
-- [For those who need more: RTFM](https://github.com/mtkachenk0/paradocs/wiki)
+Please read the [documentation](https://paradocs.readthedocs.io/en/latest)

data/docs/changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.1.2
+- Regenerate structures each time without saving them into instance attributes.
+
+## 1.1.1
+- Fixed bug with missing `errors` meta key in `Structure#all_nested` and `Structure#all_flatten` methods.
+- Fixed bug with absent `nested_name` meta key in `#Structure#all_nested` method.
+- Added opportunity to sort generated by `PayloadBuilder` payload in the way it is described in schema.
+
+## 1.1.0
+> `Schema#structure` is not comptatible with previous versions
+
+- Added `Paradocs::Extensions::StructureBuilder`. See [more](payload_builder)
+- `Parardocs::Extensions::Structure` has replaced `Paradocs::Extensions::Insides` and changed `Schema#structure` behavior
+- `Paradocs::Extensions::Structure` got more structure generation methods. See [Documentation Generation](documentation_generation)
+

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,304 @@
+# 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",
+    nested_name: "data",
+    structure: {
+      "role"       => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+      "test_field" => {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"},
+      "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"},
+      "extra"      => {
+        type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra",
+        structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"}}
+      }
+    }
+  }
+}
+all_nested[:test_subschema] # =>
+{
+  _errors:     [],
+  "data" => {
+    type:      :object,
+    required:  true,
+    present:   true,
+    json_path: "$.data",
+    nested_name: "data",
+    structure: {
+      "role"  => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+      "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"},
+      "extra" => {
+        type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra",
+        structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"}}
+      }
+    }
+  }
+}
+```
+
+## 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", nested_name: "data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"},
+    "data.test_field"  => {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"}
+  },
+  test_subschema: {
+    _errors: [],
+    "data"             => {type: :object, required: true, present: true, json_path: "$.data", nested_name: "data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"},
+    "data.test1"       => {required: true, present: true, json_path: "$.data.test1", nested_name: "data.test1"}
+  }
+}
+```
+
+## Passing a block
+Given block to the methods above (`#flatten`, `#nested`, `#all_flatten`, `#all_nested`) will be executed for
+each field, passing you as arguments `field.key` and `field.meta`. Mutating the second argument `field.meta`
+will reflect onto returned `meta`.
+
+## 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
+```
+