param_param 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61d152a83cea632bd4e660508c5dc62d26231e9bb60a35626e1991548171e205
-  data.tar.gz: 28d02503d7fc9a374d1e555c3e9328aac9418194ed6520989165b66fe5d4a3cd
+  metadata.gz: 8ef6579d2ab3739b51f2987d16d8832e5447a669c1b0fdaebefc052a86ce502d
+  data.tar.gz: 331d8721dbdb989c3fa7f01da832d860a34f6207be0a68601651e6ef534685cb
 SHA512:
-  metadata.gz: bdef7f585fc8f1050327bcdbe0946cc3255eca321c2f43b17fd42035cdc4d029f5d85011f91e01e2813af50b9e47ae70593f676078e483611efeed2e2a3f583b
-  data.tar.gz: '004692833ec9cefe0d4ebdc6ec02ffa1c4de71ef38995e03aa62eecf2cbe4e8fa839f75a9119ca4adcab5576742909d69955f332f5e833c01965544fdd54c504'
+  metadata.gz: f21bfc4dfcd7fb9e3079aa9776665b408e413af23ceef696e9f06891957b0d7f7a37e8ed21449896db5a8a44ef82c9535c0ceb41a5a7ec00c3f88d8c84f6c6fe
+  data.tar.gz: b32827903bd128ea3477162864e39cd83eefebb57d5d08af8d3458b4880e9aab8b2560413a53b6c2d0ea231d40ba40ae0e79b7e03ae90874e59eda5393402bc7

data/README.md

@@ -1,4 +1,77 @@
 # param_param
-Params parser built on lambdas.
+Lambda powered pipelines.
+Define pipelines transforming hash values.
 
 Inspired by Martin Chabot's [Simple Functional Strong Parameters In Ruby](https://blog.martinosis.com/blog/simple-functional-strong-params-in-ruby) article.
+
+# Examples
+## Validate and transform a user provided data in a web application.
+
+```
+require 'param_param'
+require 'param_param/std'
+
+class MyParams
+  include ParamParam
+  include ParamParam::Std
+
+  # You can add your own actions
+  CAPITALIZED = ->(option) { Success.new(Optiomist.some(option.value.capitalize)) }
+end
+
+user_params = MyParams.define do |p|
+  {
+    name: p::REQUIRED.(p::ALL_OF.([p::STRING, p::MIN_SIZE.(1), p::MAX_SIZE.(50), p::CAPITALIZED])),
+    admin: p::REQUIRED.(p::BOOL),
+    age: p::OPTIONAL.(p::ALL_OF.([p::INTEGER, p::GT.(0)])),
+  }
+end
+
+params, errors = user_params.(
+  name: 'JOHN',
+  admin: '0',
+  age: '30',
+  race: 'It is not important',
+)
+
+params # {:name=>"John", :admin=>false, :age=>30}
+errors # {}
+
+params, errors = UserParams.new.process(admin: 'no', age: 'very old')
+params # {:admin=>false}
+errors # {:name=>:missing, :age=>:not_integer}
+```
+
+## Perform some chain of operations on provided data.
+```
+require 'param_param'
+
+require 'param_param'
+
+module Mather
+  include ParamParam
+
+  ADD = ->(value, option) { Success.new(Optiomist.some(option.value + value)) }.curry
+  MUL = ->(value, option) { Success.new(Optiomist.some(option.value * value)) }.curry
+  SUB = ->(value, option) { Success.new(Optiomist.some(option.value - value)) }.curry
+end
+
+rules = Mather.define do |m|
+  {
+    a: m::ADD.(2),
+    b: m::MUL.(2),
+    c: m::SUB.(2),
+    d: m::ALL_OF.([m::ADD.(2), m::MUL.(2), m::SUB.(2)]),
+  }
+end
+
+params, errors = rules.(
+  a: 10,
+  b: 10,
+  c: 10,
+  d: 10,
+)
+
+params # {:a=>12, :b=>20, :c=>8, :d=>22}
+errors # {}
+```

data/lib/param_param/actions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ParamParam
+  # Defines actions to process hash values.
+  #
+  # An action is a lambda function assigned to a key.
+  # When a hash with values is provied, a value related to a key of the same name as the one the action is assigned to, processes the value.
+  #
+  # An action needs to be a lambda taking +Optiomist+ option as parameter and returning either:
+  # - +ParamParam::Success+ with processed option
+  # - +ParamParam::Failure+ with an error
+  #
+  # Example:
+  #  actions = Actions.new(
+  #    key: lambda { |option| option.some? ? Success.new(process(option.value)) : Failure.new(:missing) },
+  #    ...
+  #  )
+  class Actions
+    def initialize(actions)
+      @actions = actions
+    end
+
+    # It takes a hash and processes values related to a key by an action assigned to the same key.
+    #
+    # It returns two hashes:
+    # - if a value related to a key can be procesed by an action,
+    #   the result is bound to the key and added to the first params hash
+    # - if a value related to a key can't be processed by an action,
+    #   the error is bound to the key and added to the last errors hash
+    def call(params)
+      results = actions.to_h do |key, fn|
+        option = params.key?(key) ? optionize(params[key]) : Optiomist.none
+        [key, fn.call(option)]
+      end
+
+      errors = results.select { |_, result| result.failure? }
+                      .transform_values(&:error)
+      params = results.select { |_, result| result.success? && result.value.some? }
+                      .transform_values { |result| result.value.value }
+      [params, errors]
+    end
+
+    private
+
+    attr_reader :actions
+
+    # Converts provided value to +Optiomist::Some+.
+    # If the value is already +Optiomist::Some+ or +Optiomist::None+ returns it untouched.
+    def optionize(value)
+      if value.is_a?(Optiomist::Some) || value.is_a?(Optiomist::None)
+        value
+      else
+        Optiomist.some(value)
+      end
+    end
+  end
+end

data/lib/param_param/std.rb

@@ -1,168 +1,133 @@
 # frozen_string_literal: true
 
-# It contains a collection of some useful rules.
 module ParamParam
-  # Some string values that can be considered as +true+ (thank you dry-rb for inspiration).
-  TRUE_VALUES = %w[1 on On ON t true True TRUE T y yes Yes YES Y].freeze
-  # Some string values that can be considered as +false+ (thank you dry-rb for inspiration).
-  FALSE_VALUES = %w[0 off Off OFF f false False FALSE F n no No NO N].freeze
-
-  NOT_GTE = :not_gte
-  NOT_GT = :not_gt
-  NOT_LTE = :not_lte
-  NOT_LT = :not_lt
-  NOT_INCLUDED = :not_included
-  TOO_LONG = :too_long
-  TOO_SHORT = :too_short
-
-  NON_BOOL = :non_bool
-  NON_DECIMAL = :non_decimal
-  NON_INTEGER = :non_integer
-  NON_STRING = :non_string
-
-  # Verifies inclusion of a value in a collection.
-  #
-  # Returns
-  #  lambda { |collection, option| ... }.
-  #
-  # Verifies if value of the +option+ is included in the provided +collection+.
-  def self.included_in
-    lambda { |collection, option|
-      collection.include?(option.value) ? Success.new(option) : Failure.new(NOT_INCLUDED)
-    }.curry
-  end
+  # It defines some actions that can be useful in an everyday life.
+  module Std
+    # Some string values that can be considered as +true+ (thank you dry-rb for inspiration).
+    TRUE_VALUES = %w[1 on On ON t true True TRUE T y yes Yes YES Y].freeze
+    # Some string values that can be considered as +false+ (thank you dry-rb for inspiration).
+    FALSE_VALUES = %w[0 off Off OFF f false False FALSE F n no No NO N].freeze
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the +option+'s value is greater than or equal to the provided +limit+.
-  def self.gte
-    ->(limit, option) { option.value >= limit ? Success.new(option) : Failure.new(NOT_GTE) }.curry
-  end
+    MISSING_ERR = :missing
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the +option+'s value is greater than the provided +limit+.
-  def self.gt
-    ->(limit, option) { option.value > limit ? Success.new(option) : Failure.new(NOT_GT) }.curry
-  end
+    NOT_GTE_ERR = :not_gte
+    NOT_GT_ERR = :not_gt
+    NOT_LTE_ERR = :not_lte
+    NOT_LT_ERR = :not_lt
+    NOT_INCLUDED_ERR = :not_included
+    TOO_LONG_ERR = :too_long
+    TOO_SHORT_ERR = :too_short
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the +option+'s value is less than or equal to the provided +limit+.
-  def self.lte
-    ->(limit, option) { option.value <= limit ? Success.new(option) : Failure.new(NOT_LTE) }.curry
-  end
+    NOT_BOOL_ERR = :not_bool
+    NOT_DECIMAL_ERR = :not_decimal
+    NOT_INTEGER_ERR = :not_integer
+    NOT_STRING_ERR = :not_string
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the +option+'s value is less than the provided +limit+.
-  def self.lt
-    ->(limit, option) { option.value < limit ? Success.new(option) : Failure.new(NOT_LT) }.curry
-  end
+    # Verifies inclusion of a value in a collection.
+    #
+    # Verifies if value of the +option+ is included in the provided +collection+.
+    INCLUDED_IN = lambda do |collection, option|
+      collection.include?(option.value) ? Success.new(option) : Failure.new(NOT_INCLUDED_ERR)
+    end.curry
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the size of the value in +option+ does not exceed provided +limit+.
-  def self.max_size
-    lambda { |limit, option|
-      option.value.size <= limit ? Success.new(option) : Failure.new(TOO_LONG)
-    }.curry
-  end
+    # Describes an optional value.
+    #
+    # If +option+ is the +Optiomist::None+ it succeeds causing the parameter not to be included in the final result.
+    # Otherwise executes the funciton +fn+ for the option.
+    OPTIONAL = lambda do |fn, option|
+      case option
+      in Optiomist::None
+        Success.new(option)
+      in Optiomist::Some
+        fn.call(option)
+      end
+    end.curry
 
-  # Returns
-  #  lambda { |limit, option| ... }.
-  #
-  # Checks if the size of the value in +option+ is not lower than the provided +limit+.
-  def self.min_size
-    lambda { |limit, option|
-      option.value.size >= limit ? Success.new(option) : Failure.new(TOO_SHORT)
-    }.curry
-  end
+    # Describes a required value.
+    #
+    # It fails if +option+ is a +Optiomist::None+. Otherwise executes the funciton +fn+ for the option.
+    REQUIRED = lambda do |fn, option|
+      case option
+      in Optiomist::None
+        Failure.new(MISSING_ERR)
+      in Optiomist::Some
+        fn.call(option)
+      end
+    end.curry
 
-  # Returns
-  #  lambda { |option| ... }.
-  #
-  # Removes leading and trailing spaces from string provided in +option+'s value.
-  def self.stripped
-    ->(option) { Success.new(Optiomist.some(option.value.strip)) }
-  end
+    # Checks if the +option+'s value is greater than or equal to the provided +limit+.
+    GTE = ->(limit, option) { option.value >= limit ? Success.new(option) : Failure.new(NOT_GTE_ERR) }.curry
+
+    # Checks if the +option+'s value is greater than the provided +limit+.
+    GT = ->(limit, option) { option.value > limit ? Success.new(option) : Failure.new(NOT_GT_ERR) }.curry
+
+    # Checks if the +option+'s value is less than or equal to the provided +limit+.
+    LTE = ->(limit, option) { option.value <= limit ? Success.new(option) : Failure.new(NOT_LTE_ERR) }.curry
+
+    # Checks if the +option+'s value is less than the provided +limit+.
+    LT = ->(limit, option) { option.value < limit ? Success.new(option) : Failure.new(NOT_LT_ERR) }.curry
 
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # Converts provided +option+'s value to integer.
-  # If the conversion is not possible it fails, otherwise executes the provider function +fn+
-  # for the converted integer value.
-  def self.integer
-    lambda { |fn, option|
+    # Checks if the size of the value in +option+ does not exceed provided +limit+.
+    MAX_SIZE = lambda do |limit, option|
+      option.value.size <= limit ? Success.new(option) : Failure.new(TOO_LONG_ERR)
+    end.curry
+
+    # Checks if the size of the value in +option+ is not lower than the provided +limit+.
+    MIN_SIZE = lambda do |limit, option|
+      option.value.size >= limit ? Success.new(option) : Failure.new(TOO_SHORT_ERR)
+    end.curry
+
+    # Removes leading and trailing spaces from string provided in +option+'s value.
+    STRIPPED = ->(option) { Success.new(Optiomist.some(option.value.strip)) }
+
+    # Converts provided +option+'s value to integer.
+    # If the conversion is not possible it fails.
+    INTEGER = lambda do |option|
       begin
         integer_value = Integer(option.value)
       rescue StandardError
-        return Failure.new(NON_INTEGER)
+        return Failure.new(NOT_INTEGER_ERR)
       end
-      fn.call(Optiomist.some(integer_value))
-    }.curry
-  end
+      Success.new(Optiomist.some(integer_value))
+    end
 
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # Converts provided +option+'s value to float.
-  # If the conversion is not possible it fails, otherwise executes the provider function +fn+
-  # for the converted float value.
-  def self.decimal
-    lambda { |fn, option|
+    # Converts provided +option+'s value to float.
+    # If the conversion is not possible it fails.
+    DECIMAL = lambda do |option|
       begin
         float_value = Float(option.value)
       rescue StandardError
-        return Failure.new(NON_DECIMAL)
+        return Failure.new(NOT_DECIMAL_ERR)
       end
-      fn.call(Optiomist.some(float_value))
-    }.curry
-  end
+      Success.new(Optiomist.some(float_value))
+    end
 
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # Converts provided +option+'s value to boolean.
-  # If the conversion is not possible it fails, otherwise executes the provider function +fn+
-  # for the converted boolean value.
-  def self.bool
-    lambda { |fn, option|
+    # Converts provided +option+'s value to boolean.
+    # If the conversion is not possible it fails.
+    BOOL = lambda do |option|
       case option
       in Optiomist::Some
         if [true, *TRUE_VALUES].include?(option.value)
-          fn.call(Optiomist.some(true))
+          Success.new(Optiomist.some(true))
         elsif [false, *FALSE_VALUES].include?(option.value)
-          fn.call(Optiomist.some(false))
+          Success.new(Optiomist.some(false))
         else
-          Failure.new(NON_BOOL)
+          Failure.new(NOT_BOOL_ERR)
         end
       in Optiomist::None
-        Failure.new(NON_BOOL)
+        Failure.new(NOT_BOOL_ERR)
       end
-    }.curry
-  end
+    end
 
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # Converts provided +option+'s value to string.
-  # If the conversion is not possible it fails, otherwise executes the provider function +fn+
-  # for the converted string value.
-  def self.string
-    lambda { |fn, option|
+    # Converts provided +option+'s value to string.
+    # If the conversion is not possible it fails.
+    STRING = lambda do |option|
       case option
       in Optiomist::Some
-        fn.call(Optiomist.some(option.value.to_s))
+        Success.new(Optiomist.some(option.value.to_s))
       in Optiomist::None
-        Failure.new(NON_STRING)
+        Failure.new(NOT_STRING_ERR)
       end
-    }.curry
+    end
   end
 end

data/lib/param_param.rb

@@ -2,156 +2,38 @@
 
 require 'optiomist'
 require 'param_param/result'
-require 'param_param/std'
+require 'param_param/actions'
 
-# The main purpose of this module is to convert hash data
-# applying a chain of rules to values in the provided hash.
+# It allows to define actions that transform hash values.
+# Each actions is bound to a particular key and processes a value related to that key.
 #
-# It can be used to process form data in a web application converting
-# user provided data to values understood by the application and validate
-# it the data fulfills constraints required by the application.
-#
-# Example:
-#
-#   class UserOperation
-#     Rules = ParamParam.define.(
-#       name: ParamParam.required.(
-#         ParamParam.string.(ParamParam.all_of.([ParamParam.not_nil, ParamParam.stripped, ParamParam.max_size.(50)]))
-#       ),
-#       admin: ParamParam.required.(ParamParam.bool.(ParamParam.any)),
-#       age: ParamParam.optional.(ParamParam.integer.(ParamParam.gt.(0))),
-#     )
-#
-#     def create(name:, age:)
-#       params, errors = Rules.(name: name, age: age)
-#       throw errors unless errors.empty?
-#
-#       # do something with params
-#     end
-#   end
+# Actions could be chained and executed one by one.
+# An actions receives a value from a previous action and is expected to return successful or failed result.
+# A successful result contains a new value being the result of the processing.
+# The new value is passed further in the chain to the next action.
+# A failed result contains a message from an action saying why a particular value can't be processed.
+# Following actions in the chain are not executed.
 module ParamParam
-  MISSING = :missing
-  BLANK = :blank
-
-  # Converts provided value to +Optiomist::Some+.
-  # If the value is already +Optiomist::Some+ or +Optiomist::None+ returns it untouched.
-  def self.optionize(value)
-    if value.is_a?(Optiomist::Some) || value.is_a?(Optiomist::None)
-      value
-    else
-      Optiomist.some(value)
-    end
-  end
-
-  # Verifies if provided value is nil, empty string or string consisting only from spaces.
-  def self.blank?(value)
-    value.nil? || (value.is_a?(String) && value.strip.empty?)
+  def self.included(base)
+    base.extend(ClassMethods)
   end
 
-  # Returns lambda that allows defining a set of rules and bind them to symbols.
-  # Later those rules can be applied to parameters provided in a for of a hash.
-  # Each rule defined for a given key processes a value related to the same key in provided parameters.
-  #   lambda { |rules, params| ... }
-  #
-  # The lambda returns two hashes:
-  # - if a value related to a key can be procesed by the rules,
-  #   the result is bound to the key and added to the first hash
-  # - if a rule can't be applied to a value,
-  #   the error is bound to the key and added to the second hash
-  #
-  # Each rule needs to be a lambda taking +Optiomist+ as the only or the last parameter and returning either:
-  # - +ParamParam::Success+ with processed option
-  # - +ParamParam::Failure+ with an error
-  def self.define
-    lambda { |rules, params|
-      results = rules.to_h do |key, fn|
-        option = params.key?(key) ? optionize(params[key]) : Optiomist.none
-        [key, fn.call(option)]
-      end
-
-      errors = results.select { |_, result| result.failure? }
-                      .transform_values(&:error)
-      params = results.select { |_, result| result.success? && result.value.some? }
-                      .transform_values { |result| result.value.value }
-      [params, errors]
-    }.curry
+  module ClassMethods
+    def define(&)
+      Actions.new(yield(self))
+    end
   end
 
-  # It return lambda that allows defining a chain of rules that will be applied one by one
-  # to value processed by a previous rule.
+  # A chain of actions that are executed consecutively
+  # and pass a value from a previous action to the following one.
   #
-  # Returns:
-  #   lambda { |fns, option| ... }
-  # If some rule fails the chain is broken and value stops being processed.
-  def self.all_of
-    lambda { |fns, option|
+  # If some action fails the chain is broken and value stops being processed.
+  ALL_OF = lambda do |fns, option|
       fns.reduce(Success.new(option)) { |result, fn| result.failure? ? result : fn.call(result.value) }
-    }.curry
-  end
+  end.curry
 
-  # Returns
-  #  lambda { |option| ... }.
-  #
   # Always succeeds with the provided +option+.
-  def self.any
-    ->(option) { Success.new(option) }
-  end
-
-  # Describes an optional value.
-  #
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # If +option+ is the +Optiomist::None+ it succeeds causing the parameter not to be included in the final result.
-  # Otherwise executes the funciton +fn+ for the option.
-  def self.optional
-    lambda { |fn, option|
-      case option
-      in Optiomist::None
-        Success.new(option)
-      in Optiomist::Some
-        fn.call(option)
-      end
-    }.curry
-  end
-
-  # Describes a required value.
-  #
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # If +option+ is a +Optiomist::None+ it fails otherwise executes the funciton +fn+ for the option.
-  def self.required
-    lambda { |fn, option|
-      case option
-      in Optiomist::None
-        Failure.new(MISSING)
-      in Optiomist::Some
-        fn.call(option)
-      end
-    }.curry
-  end
-
-  # Converts blank value to nil or passes non blank value to next rule.
-  #
-  # Returns
-  #  lambda { |fn, option| ... }.
-  #
-  # If provided +option+'s value is blank it succeeds with +nil+
-  # otherwise executes provided function for the +option+.
-  def self.blank_to_nil_or
-    lambda { |fn, option|
-      blank?(option.value) ? Success.new(Optiomist.some(nil)) : fn.call(option)
-    }.curry
-  end
-
-  # Verifies if value is not blank.
-  #
-  # Returns
-  #  lambda { |option| ... }.
-  #
-  # It fails if provided +option+ is blank, otherwise succeeds with the +option+.
-  def self.not_blank
-    ->(option) { blank?(option.value) ? Failure.new(BLANK) : Success.new(option) }
+  ANY = lambda do |option|
+    Success.new(option)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: param_param
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Michał Radmacher
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-11 00:00:00.000000000 Z
+date: 2024-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: optiomist
@@ -35,6 +35,7 @@ files:
 - LICENSE
 - README.md
 - lib/param_param.rb
+- lib/param_param/actions.rb
 - lib/param_param/result.rb
 - lib/param_param/std.rb
 homepage: https://github.com/mradmacher/param_param
@@ -57,8 +58,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
-summary: Params parser built on lambdas
+summary: Lambda powered processing of hash values
 test_files: []