paradocs 1.0.22 → 1.1.2

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

data/docs/schema.md

@@ -0,0 +1,294 @@
+# Schema
+## Expanding fields dynamically
+
+Sometimes you don't know the exact field names but you want to allow arbitrary fields depending on a given pattern.
+
+```ruby
+# with this payload:
+# {
+#   title: "A title",
+#   :"custom_attr_Color" => "red",
+#   :"custom_attr_Material" => "leather"
+# }
+
+schema = Paradocs::Schema.new do
+  field(:title).type(:string).present
+  # here we allow any field starting with /^custom_attr/
+  # this yields a MatchData object to the block
+  # where you can define a Field and validations on the fly
+  # https://ruby-doc.org/core-2.2.0/MatchData.html
+  expand(/^custom_attr_(.+)/) do |match|
+    field(match[1]).type(:string).present
+  end
+end
+
+results = schema.resolve({
+  title: "A title",
+  :"custom_attr_Color" => "red",
+  :"custom_attr_Material" => "leather",
+  :"custom_attr_Weight" => "",
+})
+
+results.ouput[:Color] # => "red"
+results.ouput[:Material] # => "leather"
+results.errors["$.Weight"] # => ["is required and value must be present"]
+```
+
+NOTES: dynamically expanded field names are not included in `Schema#structure` metadata, and they are only processes if fields with the given expressions are present in the payload. This means that validations applied to those fields only run if keys are present in the first place.
+
+
+## Cloning schemas
+
+The `#clone` method returns a new instance of a schema with all field definitions copied over.
+
+```ruby
+new_schema = original_schema.clone
+```
+
+New copies can be further manipulated without affecting the original.
+
+```ruby
+# See below for #policy and #ignore
+new_schema = original_schema.clone.policy(:declared).ignore(:id) do |sc|
+  field(:another_field).present
+end
+```
+
+## Merging schemas
+
+The `#merge` method will merge field definitions in two schemas and produce a new schema instance.
+
+```ruby
+basic_user_schema = Paradocs::Schema.new do
+  field(:name).type(:string).required
+  field(:age).type(:integer)
+end
+
+friends_schema = Paradocs::Schema.new do
+  field(:friends).type(:array).schema do
+    field(:name).required
+    field(:email).policy(:email)
+  end
+end
+
+user_with_friends_schema = basic_user_schema.merge(friends_schema)
+
+results = user_with_friends_schema.resolve(input)
+```
+
+Fields defined in the merged schema will override fields with the same name in the original schema.
+
+```ruby
+required_name_schema = Paradocs::Schema.new do
+  field(:name).required
+  field(:age)
+end
+
+optional_name_schema = Paradocs::Schema.new do
+  field(:name)
+end
+
+# This schema now has :name and :age fields.
+# :name has been redefined to not be required.
+new_schema = required_name_schema.merge(optional_name_schema)
+```
+
+
+
+### Reusing nested schemas
+
+You can optionally use an existing schema instance as a nested schema:
+
+```ruby
+friends_schema = Paradocs::Schema.new do
+  field(:friends).type(:array).schema do
+    field(:name).type(:string).required
+    field(:email).policy(:email)
+  end
+end
+
+person_schema = Paradocs::Schema.new do
+  field(:name).type(:string).required
+  field(:age).type(:integer)
+  # Nest friends_schema
+  field(:friends).type(:array).schema(friends_schema)
+end
+```
+
+### Schema-wide policies
+
+Sometimes it's useful to apply the same policy to all fields in a schema.
+
+For example, fields that are _required_ when creating a record might be optional when updating the same record (ie. _PATCH_ operations in APIs).
+
+```ruby
+class UpdateUserForm < CreateUserForm
+  schema.policy(:declared)
+end
+```
+
+This will prefix the `:declared` policy to all fields inherited from the parent class.
+This means that only fields whose keys are present in the input will be validated.
+
+Schemas with default policies can still define or re-define fields.
+
+```ruby
+class UpdateUserForm < CreateUserForm
+  schema.policy(:declared) do
+    # Validation will only run if key exists
+    field(:age).type(:integer).present
+  end
+end
+```
+
+### Ignoring fields defined in the parent class
+
+Sometimes you'll want a child class to inherit most fields from the parent, but ignoring some.
+
+```ruby
+class CreateUserForm
+  include Paradocs::DSL
+
+  schema do
+    field(:uuid).present
+    field(:status).required.options(["inactive", "active"])
+    field(:name)
+  end
+end
+```
+
+The child class can use `ignore(*fields)` to ignore fields defined in the parent.
+
+```ruby
+class UpdateUserForm < CreateUserForm
+  schema.ignore(:uuid, :status) do
+    # optionally add new fields here
+  end
+end
+```
+
+### Schema options
+
+Another way of modifying inherited schemas is by passing options.
+
+```ruby
+class CreateUserForm
+  include Paradocs::DSL
+
+  schema(default_policy: :noop) do |opts|
+    field(:name).policy(opts[:default_policy]).type(:string).required
+    field(:email).policy(opts[:default_policy).policy(:email).required
+    field(:age).type(:integer)
+  end
+
+  # etc
+end
+```
+
+The `:noop` policy does nothing. The sub-class can pass its own _default_policy_.
+
+```ruby
+class UpdateUserForm < CreateUserForm
+  # this will only run validations keys existing in the input
+  schema(default_policy: :declared)
+end
+```
+
+## A pattern: changing schema policy on the fly.
+
+You can use a combination of `#clone` and `#policy` to change schema-wide field policies on the fly.
+
+For example, you might have a form object that supports creating a new user and defining mandatory fields.
+
+```ruby
+class CreateUserForm
+  include Paradocs::DSL
+
+  schema do
+    field(:name).present
+    field(:age).present
+  end
+
+  attr_reader :errors, :params
+
+  def initialize(payload: {})
+    results = self.class.schema.resolve(payload)
+    @errors = results.errors
+    @params = results.output
+  end
+
+  def run!
+    User.create(params)
+  end
+end
+```
+
+Now you might want to use the same form object to _update_ and existing user supporting partial updates.
+In this case, however, attributes should only be validated if the attributes exist in the payload. We need to apply the `:declared` policy to all schema fields, only if a user exists.
+
+We can do this by producing a clone of the class-level schema and applying any necessary policies on the fly.
+
+```ruby
+class CreateUserForm
+  include Paradocs::DSL
+
+  schema do
+    field(:name).present
+    field(:age).present
+  end
+
+  attr_reader :errors, :params
+
+  def initialize(payload: {}, user: nil)
+    @payload = payload
+    @user = user
+
+    # pick a policy based on user
+    policy = user ? :declared : :noop
+    # clone original schema and apply policy
+    schema = self.class.schema.clone.policy(policy)
+
+    # resolve params
+    results = schema.resolve(params)
+    @errors = results.errors
+    @params = results.output
+  end
+
+  def run!
+    if @user
+      @user.update_attributes(params)
+    else
+      User.create(params)
+    end
+  end
+end
+```
+
+## Multiple schema definitions
+
+Form objects can optionally define more than one schema by giving them names:
+
+```ruby
+class UpdateUserForm
+  include Paradocs::DSL
+
+  # a schema named :query
+  # for example for query parameters
+  schema(:query) do
+    field(:user_id).type(:integer).present
+  end
+
+  # a schema for PUT body parameters
+  schema(:payload) do
+    field(:name).present
+    field(:age).present
+  end
+end
+```
+
+Named schemas are inherited and can be extended and given options in the same way as the nameless version.
+
+Named schemas can be retrieved by name, ie. `UpdateUserForm.schema(:query)`.
+
+If no name given, `.schema` uses `:schema` as default schema name.
+