typed_params 0.2.0

data/lib/typed_params/parameter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'typed_params/path'
+
+module TypedParams
+  class Parameter
+    attr_accessor :key,
+                  :value
+
+    attr_reader :schema,
+                :parent
+
+    def initialize(key:, value:, schema:, parent: nil)
+      @key    = key
+      @value  = value
+      @schema = schema
+      @parent = parent
+    end
+
+    def array?  = Types.array?(value)
+    def hash?   = Types.hash?(value)
+    def scalar? = Types.scalar?(value)
+    def parent? = parent.present?
+
+    def path
+      key = @key == ROOT ? nil : @key
+
+      @path ||= Path.new(*parent&.path&.keys, *key)
+    end
+
+    def key?(key) = keys.include?(key)
+    alias :has_key? :key?
+
+    def keys?(*keys) = keys.all? { key?(_1) }
+    alias :has_keys? :keys?
+
+    def keys
+      return [] if
+        schema.children.blank?
+
+      case value
+      when Array
+        (0...value.size).to_a
+      when Hash
+        value.keys
+      else
+        []
+      end
+    end
+
+    def delete
+      raise NotImplementedError, "cannot delete param: #{key.inspect}" unless
+        parent?
+
+      case parent.value
+      when Array
+        parent.value.delete(self)
+      when Hash
+        parent.value.delete(
+          parent.value.key(self),
+        )
+      end
+    end
+
+    def unwrap(formatter: schema.formatter, controller: nil)
+      v = case value
+          when Hash
+            value.transform_values { _1.respond_to?(:unwrap) ? _1.unwrap : _1 }
+          when Array
+            value.map { _1.respond_to?(:unwrap) ? _1.unwrap : _1 }
+          else
+            value.respond_to?(:unwrap) ? value.unwrap : value
+          end
+
+      if formatter.present?
+        v = case formatter.arity
+            when 2
+              formatter.call(v, controller:)
+            when 1
+              formatter.call(v)
+            end
+      end
+
+      v
+    end
+
+    # Delegate everything else to the value
+    def respond_to_missing?(method_name, ...) = value.respond_to?(method_name, ...)
+    def method_missing(method_name, ...)      = value.send(method_name, ...)
+
+    def deconstruct_keys(keys) = { key:, value: }
+    def deconstruct            = value
+
+    def inspect
+      value = unwrap(formatter: nil)
+
+      "#<#{self.class.name} key=#{key.inspect} value=#{value.inspect}>"
+    end
+  end
+end

data/lib/typed_params/parameterizer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Parameterizer
+    def initialize(schema:, parent: nil)
+      @schema = schema
+      @parent = parent
+    end
+
+    def call(key: ROOT, value:)
+      return value if
+        value.is_a?(Parameter)
+
+      return nil if
+        key == ROOT &&
+        value.nil?
+
+      case schema.children
+      when Array
+        parameterize_array_schema(key:, value:)
+      when Hash
+        parameterize_hash_schema(key:, value:)
+      else
+        parameterize_value(key:, value:)
+      end
+    end
+
+    private
+
+    attr_reader :schema,
+                :parent
+
+    def parameterize_array_schema(key:, value:)
+      return parameterize_value(key:, value:) unless
+        value.is_a?(Array)
+
+      param = Parameter.new(key:, value: [], schema:, parent:)
+
+      value.each_with_index do |v, i|
+        unless schema.children.nil?
+          child = schema.children.fetch(i) { schema.boundless? ? schema.children.first : nil }
+          if child.nil?
+            raise UnpermittedParameterError.new('unpermitted parameter', path: Path.new(*param.path.keys, i), source: schema.source) if
+              schema.strict?
+
+            next
+          end
+
+          param << Parameterizer.new(schema: child, parent: param).call(key: i, value: v)
+        else
+          param << Parameter.new(key: i, value: v, schema:, parent: param)
+        end
+      end
+
+      param
+    end
+
+    def parameterize_hash_schema(key:, value:)
+      return parameterize_value(key:, value:) unless
+        value.is_a?(Hash)
+
+      param = Parameter.new(key:, value: {}, schema:, parent:)
+
+      value.each do |k, v|
+        unless schema.children.nil?
+          child = schema.children.fetch(k) { nil }
+          if child.nil?
+            raise UnpermittedParameterError.new('unpermitted parameter', path: Path.new(*param.path.keys, k), source: schema.source) if
+              schema.strict?
+
+            next
+          end
+
+          param[k] = Parameterizer.new(schema: child, parent: param).call(key: k, value: v)
+        else
+          param[k] = Parameter.new(key: k, value: v, schema:, parent: param)
+        end
+      end
+
+      param
+    end
+
+    def parameterize_value(key:, value:)
+      Parameter.new(key:, value:, schema:, parent:)
+    end
+  end
+end

data/lib/typed_params/path.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Path
+    attr_reader :keys
+
+    def initialize(*keys, casing: TypedParams.config.path_transform)
+      @casing = casing
+      @keys   = keys
+    end
+
+    def to_json_pointer = '/' + keys.map { transform_key(_1) }.join('/')
+    def to_dot_notation = keys.map { transform_key(_1) }.join('.')
+
+    def to_s
+      keys.map { transform_key(_1) }.reduce(+'') do |s, key|
+        next s << key if s.blank?
+
+        case key
+        when Integer
+          s << "[#{key}]"
+        else
+          s << ".#{key}"
+        end
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}: #{to_s.inspect}>"
+    end
+
+    private
+
+    attr_reader :casing
+
+    def transform_string(str)
+      case casing
+      when :underscore
+        str.underscore
+      when :camel
+        str.underscore.camelize
+      when :lower_camel
+        str.underscore.camelize(:lower)
+      when :dash
+        str.underscore.dasherize
+      else
+        str
+      end
+    end
+
+    def transform_key(key)
+      return key if key.is_a?(Integer)
+
+      transform_string(key.to_s)
+    end
+  end
+end

data/lib/typed_params/pipeline.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Pipeline
+    def initialize   = @steps = []
+    def <<(step)     = steps << step
+    def call(params) = steps.reduce(params) { |v, step| step.call(v) }
+
+    private
+
+    attr_reader :steps
+  end
+end

data/lib/typed_params/processor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Processor
+    def initialize(schema:, controller: nil)
+      @controller = controller
+      @schema     = schema
+    end
+
+    def call(value)
+      params   = Parameterizer.new(schema:).call(value:)
+      pipeline = Pipeline.new
+
+      pipeline << Bouncer.new(controller:, schema:)
+      pipeline << Coercer.new(schema:)
+      pipeline << Validator.new(schema:)
+      pipeline << Transformer.new(controller:, schema:)
+
+      pipeline.call(params)
+    end
+
+    private
+
+    attr_reader :controller,
+                :schema
+  end
+end

data/lib/typed_params/schema.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Schema
+    attr_reader :validations,
+                :transforms,
+                :formatter,
+                :parent,
+                :children,
+                :source,
+                :type,
+                :key,
+                :if,
+                :unless
+
+    def initialize(
+      controller: nil,
+      source: nil,
+      strict: true,
+      parent: nil,
+      type: :hash,
+      key: nil,
+      optional: false,
+      coerce: false,
+      allow_blank: false,
+      allow_nil: false,
+      allow_non_scalars: false,
+      nilify_blanks: false,
+      noop: false,
+      inclusion: nil,
+      exclusion: nil,
+      format: nil,
+      length: nil,
+      transform: nil,
+      validate: nil,
+      if: nil,
+      unless: nil,
+      as: nil,
+      casing: TypedParams.config.key_transform,
+      &block
+    )
+      key ||= ROOT
+
+      raise ArgumentError, 'key is required for child schema' if
+        key == ROOT && parent.present?
+
+      raise ArgumentError, 'root cannot be null' if
+        key == ROOT && allow_nil
+
+      raise ArgumentError, 'source must be one of: :params or :query' unless
+        source.nil? || source == :params || source == :query
+
+      raise ArgumentError, 'inclusion must be a hash with :in key' unless
+        inclusion.nil? || inclusion.is_a?(Hash) && inclusion.key?(:in)
+
+      raise ArgumentError, 'exclusion must be a hash with :in key' unless
+        exclusion.nil? || exclusion.is_a?(Hash) && exclusion.key?(:in)
+
+      raise ArgumentError, 'format must be a hash with :with or :without keys (but not both)' unless
+        format.nil? || format.is_a?(Hash) && (
+          format.key?(:with) ^
+          format.key?(:without)
+        )
+
+      raise ArgumentError, 'length must be a hash with :minimum, :maximum, :within, :in, or :is keys (but not multiple)' unless
+        length.nil? || length.is_a?(Hash) && (
+          length.key?(:minimum) ^
+          length.key?(:maximum) ^
+          length.key?(:within) ^
+          length.key?(:in) ^
+          length.key?(:is)
+        )
+
+      @controller        = controller
+      @source            = source
+      @type              = Types[type]
+      @strict            = strict
+      @parent            = parent
+      @key               = key
+      @optional          = optional
+      @coerce            = coerce && @type.coercable?
+      @allow_blank       = key == ROOT || allow_blank
+      @allow_nil         = allow_nil
+      @allow_non_scalars = allow_non_scalars
+      @nilify_blanks     = nilify_blanks
+      @noop              = noop
+      @inclusion         = inclusion
+      @exclusion         = exclusion
+      @format            = format
+      @length            = length
+      @casing            = casing
+      @transform         = transform
+      @children          = nil
+      @if                = binding.local_variable_get(:if)
+      @unless            = binding.local_variable_get(:unless)
+      @formatter         = nil
+      @options           = {}
+
+      # Validations
+      @validations = []
+
+      @validations << Validations::Inclusion.new(inclusion) if
+        inclusion.present?
+
+      @validations << Validations::Exclusion.new(exclusion) if
+        exclusion.present?
+
+      @validations << Validations::Format.new(format) if
+        format.present?
+
+      @validations << Validations::Length.new(length) if
+        length.present?
+
+      @validations << Validations::Validation.wrap(validate) if
+        validate.present?
+
+      # Transforms
+      @transforms = []
+
+      @transforms << Transforms::KeyAlias.new(as) if
+        as.present?
+
+      @transforms << Transforms::NilifyBlanks.new if
+        nilify_blanks
+
+      @transforms << Transforms::Transform.wrap(transform) if
+        transform.present?
+
+      @transforms << Transforms::KeyCasing.new(casing) if
+        casing.present?
+
+      @transforms << Transforms::Noop.new if
+        noop
+
+      raise ArgumentError, "type #{type} is a not registered type" if
+        @type.nil?
+
+      if block_given?
+        raise ArgumentError, "type #{@type} does not accept a block" if
+          @type.present? && !@type.accepts_block?
+
+        @children = case
+                    when Types.array?(@type)
+                      []
+                    when Types.hash?(@type)
+                      {}
+                    end
+
+        self.instance_exec &block
+      end
+    end
+
+    ##
+    # format defines the final output format for the schema, transforming
+    # the params from an input format to an output format, e.g. a JSONAPI
+    # document to Rails' standard params format. This also applies the
+    # formatter's decorators onto the controller.
+    def format(format)
+      raise NotImplementedError, 'cannot define format for child schema' if
+        child?
+
+      formatter = Formatters[format]
+
+      raise ArgumentError, "invalid format: #{format.inspect}" if
+        formatter.nil?
+
+      # Apply the formatter's decorators onto the controller.
+      controller.instance_exec(&formatter.decorator) if
+        controller.present? && formatter.decorator?
+
+      @formatter = formatter
+    end
+
+    ##
+    # with defines a set of options to use for all direct children of the
+    # schema defined within the block.
+    #
+    # For example, it can be used to define a common guard:
+    #
+    #   with if: -> { ... } do
+    #     param :foo, type: :string
+    #     param :bar, type: :string
+    #     param :baz, type: :hash do
+    #       param :qux, type: :string
+    #     end
+    #   end
+    #
+    # In this example, :foo, :bar, and :baz will inherit the if: guard,
+    # but :qux will not, since it is not a direct child.
+    #
+    def with(**kwargs, &)
+      orig     = @options
+      @options = kwargs
+
+      yield
+
+      @options = orig
+    end
+
+    ##
+    # param defines a keyed parameter for a hash schema.
+    def param(key, type:, **kwargs, &block)
+      raise NotImplementedError, "cannot define param for non-hash type (got #{self.type})" unless
+        Types.hash?(children)
+
+      raise ArgumentError, "key #{key} has already been defined" if
+        children.key?(key)
+
+      children[key] = Schema.new(**options, **kwargs, key:, type:, strict:, source:, casing:, parent: self, &block)
+    end
+
+    ##
+    # params defines multiple like-parameters for a hash schema.
+    def params(*keys, **kwargs, &) = keys.each { param(_1, **kwargs, &) }
+
+    ##
+    # item defines an indexed parameter for an array schema.
+    def item(key = children&.size || 0, type:, **kwargs, &block)
+      raise NotImplementedError, "cannot define item for non-array type (got #{self.type})" unless
+        Types.array?(children)
+
+      raise ArgumentError, "index #{key} has already been defined" if
+        children[key].present? || boundless?
+
+      children << Schema.new(**options, **kwargs, key:, type:, strict:, source:, casing:, parent: self, &block)
+    end
+
+    ##
+    # items defines a set of like-parameters for an array schema.
+    def items(**kwargs, &)
+      item(0, **kwargs, &)
+
+      boundless!
+    end
+
+    def path
+      key = @key == ROOT ? nil : @key
+
+      @path ||= Path.new(*parent&.path&.keys, *key)
+    end
+
+    def keys
+      return [] if
+        children.blank?
+
+      case children
+      when Array
+        (0...children.size).to_a
+      when Hash
+        children.keys
+      else
+        []
+      end
+    end
+
+    def root?              = key == ROOT
+    def child?             = !root?
+    def children?          = !children.blank?
+    def strict?            = !!strict
+    def lenient?           = !strict?
+    def optional?          = !!@optional
+    def required?          = !optional?
+    def coerce?            = !!@coerce
+    def allow_blank?       = !!@allow_blank
+    def allow_nil?         = !!@allow_nil
+    def allow_non_scalars? = !!@allow_non_scalars
+    def nilify_blanks?     = !!@nilify_blanks
+    def boundless?         = !!@boundless
+    def indexed?           = !boundless?
+    def if?                = !@if.nil?
+    def unless?            = !@unless.nil?
+    def array?             = Types.array?(type)
+    def hash?              = Types.hash?(type)
+    def scalar?            = Types.scalar?(type)
+    def formatter?         = !!@formatter
+
+    def inspect
+      "#<#{self.class.name} key=#{key.inspect} type=#{type.inspect} children=#{children.inspect}>"
+    end
+
+    private
+
+    attr_reader :controller,
+                :options,
+                :strict,
+                :casing
+
+    def boundless! = @boundless = true
+  end
+end

data/lib/typed_params/schema_set.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'typed_params/namespaced_set'
+
+module TypedParams
+  class SchemaSet < NamespacedSet; end
+end

data/lib/typed_params/transformer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'typed_params/mapper'
+
+module TypedParams
+  class Transformer < Mapper
+    def call(params)
+      depth_first_map(params) do |param|
+        schema = param.schema
+        parent = param.parent
+
+        # Ignore nil optionals when config is enabled
+        unless schema.allow_nil?
+          if param.value.nil? && schema.optional? && TypedParams.config.ignore_nil_optionals
+            param.delete
+
+            break
+          end
+        end
+
+        schema.transforms.map do |transform|
+          key, value = transform.call(param.key, param.value)
+          if key.nil?
+            param.delete
+
+            break
+          end
+
+          # Check for nils again after transform
+          unless schema.allow_nil?
+            if value.nil? && schema.optional? && TypedParams.config.ignore_nil_optionals
+              param.delete
+
+              break
+            end
+          end
+
+          # If param's key has changed, we want to rename the key
+          # for its parent too.
+          if param.parent? && param.key != key
+            parent[key] = param.delete
+          end
+
+          param.key, param.value = key, value
+        end
+      end
+    end
+  end
+end

data/lib/typed_params/transforms/key_alias.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'typed_params/transforms/transform'
+
+module TypedParams
+  module Transforms
+    class KeyAlias < Transform
+      def initialize(as) = @as = as
+      def call(_, value) = [as, value]
+
+      private
+
+      attr_reader :as
+    end
+  end
+end

data/lib/typed_params/transforms/key_casing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'typed_params/transforms/transform'
+
+module TypedParams
+  module Transforms
+    class KeyCasing < Transform
+      def initialize(casing) = @casing = casing
+
+      def call(key, value)
+        transformed_key   = transform_key(key)
+        transformed_value = transform_value(value)
+
+        [transformed_key, transformed_value]
+      end
+
+      private
+
+      attr_reader :casing
+
+      def transform_string(str)
+        case casing
+        when :underscore
+          str.underscore
+        when :camel
+          str.underscore.camelize
+        when :lower_camel
+          str.underscore.camelize(:lower)
+        when :dash
+          str.underscore.dasherize
+        else
+          str
+        end
+      end
+
+      def transform_key(key)
+        case key
+        when String
+          transform_string(key)
+        when Symbol
+          transform_string(key.to_s).to_sym
+        else
+          key
+        end
+      end
+
+      def transform_value(value)
+        case value
+        when Hash
+          value.deep_transform_keys { transform_key(_1) }
+        when Array
+          value.map { transform_value(_1) }
+        else
+          value
+        end
+      end
+    end
+  end
+end