paradocs 1.0.24 → 1.1.4

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"}
+```
+

data/docs/payload_builder.md

@@ -0,0 +1,105 @@
+# Generate examples from the Schema
+
+> `Schema` instance provides `#example_payloads` method that returns example of all possible structures.
+
+NOTE: `PayloadBuilder` sets nil values by default. If options are given - builder will take on of them, if default is set - builder will use it.
+
+#### Example 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
+```
+
+## Generate payloads
+
+```rb
+Paradocs::Extensions::PayloadBuilder.new(schema).build! # =>
+# or
+schema.example_payloads.to_json # =>
+{
+  "subschema": {
+    "data": {
+      "name": null,
+      "role": "user",
+      "extra": [{"extra": null}],
+      "test_field": null,
+      "id": null
+    }
+  },
+  "test_subschema": {
+    "data": {
+      "name": null,
+      "role": "user",
+      "extra": [{"extra": null}],
+      "test1": null,
+      "id": null
+    }
+  }
+}
+```
+
+## Customize payload generation logic
+`PayloadBuilder#build!` arguments:
+
+1. `sort_by_schema: true` will try to return payload in the same way as declared in the schema.
+2. `&block` will be executed for each key receiving the following arguments:
+	- `key`: Field name
+	- `meta`: Field meta data (that includes (if provided) field types, presence data, policies and other meta data
+	- `example_value`: Provided by generator example value.
+	- `skip_word`: Return this argument back if you want this item to be ommitted.
+
+```rb
+block = Proc.new do |key, meta, example, skip_word|
+  if key.to_s == "name"
+    "John Smith"
+  elsif meta[:type] == :integer
+    13
+  elsif key.to_s.match? /test/
+    skip_word
+  else
+    example
+  end
+end
+schema.example_payloads(&block) # =>
+# or
+Paradocs::Extensions::PayloadBuilder.new(schema).build!(&block) # =>
+{
+  "subschema": {
+    "data": {
+      "name": "John Smith", # value is changed
+      "role": "user", # random choice from field(:user).options
+      "extra": [{"extra": null}], # null are defaults
+      "id": 13 # value is changed
+      # NOTE: fields matching with /test/ are ommitted: test_field, test1
+    }
+  },
+  "test_subschema": {
+    "data": {
+      "name": "John Smith",
+      "role": "user",
+      "extra": [{"extra": null}],
+      "id": 13
+    }
+  }
+}
+
+```

data/docs/policies.md

@@ -0,0 +1,309 @@
+# Built-In Policies
+Paradocs ships with a number of built-in policies.
+
+## Type coercions
+Type coercions (the `type` method) and validations (the `validate` method) are all _policies_.
+
+### :string
+
+Calls `:to_s` on the value
+
+```ruby
+field(:title).type(:string)
+```
+
+### :integer
+
+Calls `:to_i` on the value
+
+```ruby
+field(:age).type(:integer)
+```
+
+### :number
+
+Calls `:to_f` on the value
+
+```ruby
+field(:price).type(:number)
+```
+
+### :boolean
+
+Returns `true` or `false` (`nil` is converted to `false`).
+
+```ruby
+field(:published).type(:boolean)
+```
+
+### :datetime
+
+Attempts parsing value with [Datetime.parse](http://ruby-doc.org/stdlib-2.3.1/libdoc/date/rdoc/DateTime.html#method-c-parse). If invalid, the error will be added to the output's `errors` object.
+
+```ruby
+field(:expires_on).type(:datetime)
+```
+
+## Presence policies.
+
+### :required
+
+Check that the key exists in the input.
+
+```ruby
+field(:name).required
+
+# same as
+field(:name).policy(:required)
+```
+
+Note that `:required` policy does not validate that the value is not empty. Use `:present` for that.
+
+### :present
+
+Check that the key exists and the value is not blank.
+
+```ruby
+field(:name).present
+
+# same as
+field(:name).policy(:present)
+```
+
+If the value is a `String`, it validates that it's not blank. If an `Array`, it checks that it's not empty. Otherwise it checks that the value is not `nil`.
+
+### :declared
+
+Check that a key exists in the input, or stop any further validations otherwise.
+This is useful when chained to other validations. For example:
+
+```ruby
+field(:name).declared.present
+```
+The example above will check that the value is not empty, but only if the key exists. If the key doesn't exist no validations will run.
+
+### :default
+
+- `:default` policy is invoked when there are no field presence policies defined or used either `:required` or `:declared` policies.
+- `:default` policy is invoked when value is nil or empty
+- `:default` policy can be a proc. Proc receives the following arguments: `key, the whole payload, validation context`
+
+```ruby
+field(:role).declared.default("admin")
+field(:created_at).declared.default( ->(key, payload, context) { DateTime.now })
+```
+
+## Useful built-in policies.
+
+### :format
+
+Check value against custom regexp
+
+```ruby
+field(:salutation).policy(:format, /^Mr\/s/)
+# optional custom error message
+field(:salutation).policy(:format, /^Mr\/s\./, "must start with Mr/s.")
+```
+
+### :email
+
+```ruby
+field(:business_email).policy(:email)
+```
+
+### :gt, :gte, :lt, :lte
+
+Compare the value with a number.
+
+```ruby
+field(:age).policy(:gt, 35) # strictly greater than 35
+field(:age1).policy(:lt, 11.1) # strictly less than 11.1
+field(:age2).policy(:lte, 21) # less or equal to 21
+field(:age3).policy(:gte, 11) # greater or equal to 11
+```
+
+### :options
+
+Pass allowed values for a field
+
+```ruby
+field(:status).options(["draft", "published"])
+
+# Same as
+field(:status).policy(:options, ["draft", "published"])
+```
+
+### :length
+
+Specify value's length constraints. Calls #length under the hood.
+ - `min:` - The attribute cannot have less than the specified length.
+ - `max`  - The attribute cannot have more than the specified length.
+ - `eq`   - The attribute should be exactly equal to the specified length.
+
+```ruby
+field(:name).length(min: 5, max: 25)
+field(:name).length(eq: 10)
+```
+
+### :split
+
+Split comma-separated string values into an array.
+Useful for parsing comma-separated query-string parameters.
+
+```ruby
+field(:status).policy(:split) # turns "pending,confirmed" into ["pending", "confirmed"]
+```
+
+### :meta
+
+The `#meta` field method can be used to add custom meta data to field definitions.
+These meta data can be used later when instrospecting schemas (ie. to generate documentation or error notices).
+
+```ruby
+create_user_schema = Paradocs::Schema.new do
+  field(:name).required.type(:string).meta(label: "User's full name")
+  field(:status).options(["published", "unpublished"]).default("published")
+  field(:age).type(:integer).meta(label: "User's age")
+  field(:friends).type(:array).meta(label: "User friends").schema do
+    field(:name).type(:string).present.meta(label: "Friend full name")
+    field(:email).policy(:email).meta(label: "Friend's email")
+  end
+end
+```
+
+## Custom policies
+
+You can also register your own custom policy objects. A policy can be not inherited from `Paradocs::BasePolicy`, in this case it must implement the following methods: `#valid?`, `#coerce`, `#message`, `#meta_data`, `#policy_name`
+
+```ruby
+class MyPolicy < Paradocs::BasePolicy
+  # Validation error message, if invalid
+  def message
+    'is invalid'
+  end
+
+  # Whether or not to validate and coerce this value
+  # if false, no other policies will be run on the field
+  def eligible?(value, key, payload)
+    true
+  end
+
+  # Transform the value
+  def coerce(value, key, context)
+    value
+  end
+
+  # Is the value valid?
+  def validate(value, key, payload)
+    true
+  end
+
+  # merge this object into the field's meta data
+  def meta_data
+    {type: :string}
+  end
+end
+```
+
+
+You can register your policy with:
+
+```ruby
+Paradocs.policy :my_policy, MyPolicy
+```
+And then refer to it by name when declaring your schema fields
+
+```ruby
+field(:title).policy(:my_policy)
+```
+
+You can chain custom policies with other policies.
+
+```ruby
+field(:title).required.policy(:my_policy)
+```
+
+Note that you can also register instances.
+
+```ruby
+Paradocs.policy :my_policy, MyPolicy.new
+```
+
+For example, a policy that can be configured on a field-by-field basis:
+
+```ruby
+class AddJobTitle
+  def initialize(job_title)
+    @job_title = job_title
+  end
+
+  def message
+    'is invalid'
+  end
+
+  # Noop
+  def eligible?(value, key, payload)
+    true
+  end
+
+  # Add job title to value
+  def coerce(value, key, context)
+    "#{value}, #{@job_title}"
+  end
+
+  # Noop
+  def validate(value, key, payload)
+    true
+  end
+
+  def meta_data
+    {}
+  end
+end
+
+# Register it
+Paradocs.policy :job_title, AddJobTitle
+```
+
+Now you can reuse the same policy with different configuration
+
+```ruby
+manager_schema = Paradocs::Schema.new do
+  field(:name).type(:string).policy(:job_title, "manager")
+end
+
+cto_schema = Paradocs::Schema.new do
+  field(:name).type(:string).policy(:job_title, "CTO")
+end
+
+manager_schema.resolve(name: "Joe Bloggs").output # => {name: "Joe Bloggs, manager"}
+cto_schema.resolve(name: "Joe Bloggs").output # => {name: "Joe Bloggs, CTO"}
+```
+
+## Custom policies, short version
+
+For simple policies that don't need all policy methods, you can:
+
+```ruby
+Paradocs.policy :cto_job_title do
+  coerce do |value, key, context|
+    "#{value}, CTO"
+  end
+end
+
+# use it
+cto_schema = Paradocs::Schema.new do
+  field(:name).type(:string).policy(:cto_job_title)
+end
+```
+
+```ruby
+Paradocs.policy :over_21_and_under_25 do
+  coerce do |age, key, context|
+    age.to_i
+  end
+
+  validate do |age, key, context|
+    age > 21 && age < 25
+  end
+end