mini_defender 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fa43ad18c9eec0f5536856021d4ad91124919b193ebf402b063db104c2423bc
-  data.tar.gz: '09550f63e65490c59b43cf50b6f3454d4385655090dbe880e6408c10c50375da'
+  metadata.gz: 6442a233854e38c0ac2a50d040d132c927be919fbba2c1a0dd8a303501c53fb4
+  data.tar.gz: 28b2336b4e20828a3a3e92027c9c501902426e1ef8319b88f84d92c7589ab92b
 SHA512:
-  metadata.gz: aa5d6f0399d1fb8df563f5b86830b0e058f7343360258dceff43dc34d9e6ce381250a9c3ef5291133c3ca639681770583c2e7418d3d177c8202cd89777952ec4
-  data.tar.gz: 5dc095ea1c58329e1fe04f4977f53f08c832b51e61e4e6bb6c97ac71783793049e6ab360eac3053a0441c049b6d590b320db976f355e5727d568b09a5389b8c4
+  metadata.gz: 3ab48998b4c80d478ae46fcab7d161d8c4f2fee7c7e43c0066c9d46cf5188db1b02cb3ef578f4b4db58a48add2fbad048d443f1606a4156bfa9f724e70832a62
+  data.tar.gz: 18f49db6546dca476afbbd137e28a0f4c6e0760ee7cd9aeb083624ff0da5fbdfd6484af4a44bbfdd7a5a961935a3000cdb7662b5fa83765d78f706531fb8f1ad

data/README.md

@@ -1,8 +1,7 @@
 # MiniDefender
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mini_defender`. To experiment with that code, run `bin/console` for an interactive prompt.
+A pragmatic approach to validation in Rails inspired by Laravel's Validator.
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
@@ -14,20 +13,156 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install mini_defender
 
+
 ## Usage
 
-TODO: Write usage instructions here
+Mini Defender allows the developer to quickly and easily validate incoming requests data as the verify first step
+in the request, alongside this Mini Defender also provides the following benefits:
+
+- Concise and easy to write validation logic
+- Validate complex and nested data structures
+- More than 80 validation rules available
+- Custom validation rules
+
+The easiest way to use Mini Defender is to include the concern `MiniDefender::ValidatesInput` to your
+`ApplicationController` as follows:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include MiniDefender::ValidatesInput
+end
+```
+
+Now you will have access to a method called `validate!` which will accept a hash of keys and their respective rules.
+
+```ruby
+# frozen_string_literal: true
+class BooksController < ActionController::Base
+  def create
+    Book.create!(book_params)
+  end
+  
+  private
+  
+  def book_params
+    # Optional if you need easy access to rule definitions
+    rules = MiniDefender::Rules
+    
+    validate!({
+        'name' => 'string|required|max:255',
+        'type' => ['string', rules::In.new(Book::TYPES)],
+        'tags' => 'array',
+        'tags.*' => 'required|string|max:255',
+        'pages' => 'required|integer',
+        'author' => 'required|hash',
+        'author.name' => 'required|string',
+        'author.email' => 'email',
+    }, true)
+  end
+end
+```
+
+The `validate!` method accepts two arguments, the first is a hash of keys and rules and the second a boolean to indicate
+if you want the values to be coerced to the type indicated by rule, i.e. `integer`.
+
+Suppose we passed the following input to our app:
+
+```json
+{
+  "name": "The Story of Some Guy",
+  "type": "Biography",
+  "tags": ["inspiring", "business"],
+  "pages": "200",
+  "author": {
+    "name": "Some Guy himself",
+    "random_field": "hello i can haz hakc?"
+  }
+}
+```
+
+Notice that we have passed a string `"200"` to page instead of `200` and added an extra field to `author` called `random_field`.
+We didn't also provide an `email` field.
+
+The validation will pass, since `email` is not optional, and we will get the following `Hash` as a result:
+
+```Ruby
+{
+  'name' => 'The Story of Some Guy',
+  'type' => 'Biography',
+  'tags' => %w[inspiring business],
+  'pages' => 200,
+  'author' => {
+    'name' => 'Some Guy himself'
+  }
+}
+```
+
+You can see that `pages` has the value converted to `200` (integer), since we chose to coerce by passing `true` to `validate!`.
+You can also see that Mini Defender left out the key `random_field` as it was not a part of our validations.
+
+
+## Rendering Errors
+
+When the validation fails, an error of type `MiniDefender::ValidationError` will be raised.
+
+You can either handle the error using `rescue` or add a global `rescue_from` to handle the errors throughout the application.
+
+
+## Outside of a Controller
+
+The `validate!` method is actually the following four lines of code:
+
+```ruby
+def validate!(rules, coerced = false)
+    data = params.to_unsafe_hash.deep_stringify_keys
+    validator = MiniDefender::Validator.new(rules, data)
+    validator.validate!
+    coerced ? validator.coerced : validator.data
+end
+```
+
+You can use Mini Defender out side of the controller by creating a new instance of `MiniDefender::Validator` and calling
+any of the methods on it, see [validator.rb](./lib/mini_defender/validator.rb) for the API.
+ 
+
+## Rules
+
+Mini Defender tries to implement the same set of rules provided by Laravel, you can see the available rules here at
+[lib/mini_defender/rules](./lib/mini_defender/rules)
+
+
+## Add a Custom Rule
+
+To implement your custom rules, you need to create a new class that inherent from `MiniDefender::Rule` and implement
+at least the following:
+
+```ruby
+class MyAwesomeRule < MiniDefender::Rule
+  def self.signature
+    'all_caps'
+  end
+
+  def passes?(attribute, value, validator)
+    value.is_a?(String) && /^[A-Z]+$/.match?(value)
+  end
+
+  def message(attribute, value, validator)
+    'ONLY CAPS ALLOWED!!!'
+  end
+end
+```
 
-## Development
+After creating the class, you can register it as follows:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+MiniDefender::RulesFactory.register(MyAwesomeRule)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mini_defender.
+Bug reports and pull requests are welcome on GitHub at https://github.com/ahoshaiyan/mini_defender.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](./LICENSE.md).

data/lib/mini_defender/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MiniDefender
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mini_defender
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ali Alhoshaiyan
@@ -78,7 +78,6 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.md
-- LICENSE.txt
 - README.md
 - RULES.md
 - Rakefile

data/LICENSE.txt

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2022 Ali Alhoshaiyan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.