bizness 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bbc62c7f37f2569e45fa1eb3e49262d7724d9153
-  data.tar.gz: ff4592f89c4ddea5024faf92e1ae91d7d0a02bae
+  metadata.gz: 6be2ccb0ce9564adc8d96d444dc6be4418c1db7c
+  data.tar.gz: 0d25e8548ffb56eb352e66b974630bc5851a48e3
 SHA512:
-  metadata.gz: 6ed4818a1745adc1882e552cbcc1b93a4eef543781d029b4dbeb28120fe7d7c4e70160172880db51396240d21575edd46d9aee712d175ed862427c7cbb1df7ad
-  data.tar.gz: 7cddc1debfcb6714179ec8d7e3b9590e16865b87901fdfacb69b72087777b39e8b0bdb1b48cd4781d6492723b740062037c617d2f19efd86a68024d70b389ffa
+  metadata.gz: a634804e9296927f0d8e339845d793178ee708e86b631a389178f2c7f03cddcf77b742c177451080e1324fbbfd8280df8e7d2f8501bb9ac39ae06f3d6e146d83
+  data.tar.gz: 25b120fc67cf176b01b002db976eda1c3e254030d75d14fa3d1ba1a38b74e0585be33cebef77524f4d6eea84b4a95bb41f1a5a451e02b659e578bf86a5a79747

data/README.md

@@ -84,6 +84,63 @@ op.successful? # True if error is nil
 op.to_h
 ```
 
+### The Policy module
+
+Operations are expected to run to completion, otherwise a runtime error should be raised. Before executing an operation, you should generally ensure that the object or objects being operated against pass a certain set of criteria.
+
+We typically wrap this set of criteria in a Policy object, and if the object passes the policy we kick off the operation. You can call this policy during input validation and return the violations to the end user. However, we also like to use the policy object inside the operation as a final guard before running the operation. If the policy fails, we raise a runtime exception containing the list of violations.
+
+Since this is such a common pattern, we created the `Bizness::Policy` module. Here's an example:
+
+```ruby
+class StringFormatPolicy
+  include Bizness::Policy
+
+  attr_reader :string
+
+  def initialize(string:)
+    @string = string
+  end
+
+  private
+
+  def alphanumeric?
+    string.match(/^[[:alpha:]]+$/)
+  end
+
+  def all_caps?
+    string == string.upcase
+  end
+end
+
+policy = StringFormatPolicy.new(string: "abc123")
+policy.successful?
+#=> false
+
+policy.violations
+#=> ["String must be alphanumeric", "Characters must be all uppercase"]
+```
+
+By including the module, the object gets the `successful?` method which does the following when called:
+
+1. Introspects all private predicate methods (methods that end with a question mark) and executes them
+2. If the method returns false, it looks for a translation in an I18n YAML file
+3. It composes an 118n key using the policy's class and method name (without the question mark). For example: `policies.mock_policy.violations.all_caps`  
+4. It adds the result of the translation to the list of `violations`
+5. It returns false if any violations are found
+                                                                                                           
+An example I18n translation file looks like this:
+                                                                                                           
+```                                                                                                           
+# en.yml
+en:
+  policies:
+    mock_policy:
+      violations:
+        all_caps: "Characters must be all uppercase"
+        alphanumeric: "String must be alphanumeric"
+```
+
 ### Pubsub
 
 #### Publishing

data/bizness.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activerecord"
+  spec.add_dependency "i18n"
   spec.add_dependency "hey-pubsub", "~> 0.2.0"
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"

data/lib/bizness.rb

@@ -2,6 +2,7 @@ require "bizness/version"
 require "active_record"
 require "forwardable"
 require "hey"
+require "i18n"
 
 module Bizness
   def self.configure
@@ -24,6 +25,7 @@ end
 
 require "bizness/configuration"
 require "bizness/operation"
+require "bizness/policy"
 require "bizness/subscriber"
 require "bizness/filters/base_filter"
 require "bizness/filters/active_record_transaction_filter"

data/lib/bizness/policy.rb

@@ -0,0 +1,76 @@
+# Adds convenience methods for defining a policy object and recording its violations. To take use this module, do the
+# following:
+#
+# 1. Write one or more private predicate methods that define your policies requirements
+# 2. Define violation messages in your corresponding I18n locale YAML files
+#
+# -- string_format_policy.rb
+#
+# class StringFormatPolicy
+#   include Bizness::Policy
+#
+#   def initialize(string)
+#     @string = string
+#   end
+#
+#   private
+#
+#   attr_reader :string
+#
+#   def all_caps?
+#    string.upcase == string
+#   end
+# end
+#
+# -- en.yml
+#
+# en:
+#   policies:
+#     string_format_policy:
+#       violations:
+#         all_caps: "Must be an uppercase string"
+#
+# Example usage:
+#
+# policy = StringFormatPolicy.new("abcd")
+# policy.successful?
+# => false
+#
+# policy.violations
+# => ["Must be an uppercase string"]
+#
+module Bizness::Policy
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  def violations
+    @violations || []
+  end
+
+  def successful?
+    self.violations = []
+    self.class.__requirements__.each do |m|
+      self.violations << self.class.violation_message(m) unless send(m)
+    end
+    violations.empty?
+  end
+
+  module ClassMethods
+    def violation_message(method)
+      policy = self.name.gsub(/(.)([A-Z])/,'\1_\2').downcase
+      message_key = "policies.#{policy}.violations.#{method.to_s.delete("?")}"
+      I18n.t(message_key)
+    end
+
+    def __requirements__
+      @__requirements__ ||= begin
+        private_instance_methods(false).select { |m| m.to_s[/\?$/] }
+      end
+    end
+  end
+
+  private
+
+  attr_writer :violations
+end

data/lib/bizness/version.rb

@@ -1,3 +1,3 @@
 module Bizness
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bizness
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - ShippingEasy
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-27 00:00:00.000000000 Z
+date: 2015-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: hey-pubsub
   requirement: !ruby/object:Gem::Requirement
@@ -117,6 +131,7 @@ files:
 - lib/bizness/filters/base_filter.rb
 - lib/bizness/filters/event_filter.rb
 - lib/bizness/operation.rb
+- lib/bizness/policy.rb
 - lib/bizness/subscriber.rb
 - lib/bizness/version.rb
 homepage: ''