smart_params 5.1.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cf4e5cc079291eb9eeaad6ca13e2a79d0bbf15b2c606060e996dd2e05425442
-  data.tar.gz: 8a6fdf59b26cc8f385bb449be28dba4e5fe0841fda0f1f3bdc0e1cebfcbaf1c5
+  metadata.gz: 9f43877a67e8dd606f2f178c7d65f2ec41412f91dc4208cecc150ecfcaca7558
+  data.tar.gz: 8b5cf703c4eacabaa863e6efd8d938f4f87b417dfc6de1c80e6c6b89c4cef9be
 SHA512:
-  metadata.gz: 73d1158ecfcd1b49da42ac85991fc9673be357e7b012716aa9981fef5cc14dc0d9592280b1443029c3c924f22bcaeb2de759a3d158f0fbe2cf876393aa7b13a6
-  data.tar.gz: cb248bd6442bcab659cec87bc8e74daeb8c1304cb73009a2559b81d580276ba84392097692f6bbbc621f796826c0dfeba850ba49e62de657ca5ed817aff1aa17
+  metadata.gz: 4c3b9ae72f37f625a831a8b387457ee7f0425dabea293073b20df33796ec853af3e89f0d3279557640887ab743ae7673de3b620e691b4d5f0f050f41ef98a417
+  data.tar.gz: 3739b636c5f29142877b459d7914293970bbc97da5aad7fb1d6ed9a7636bb69d467bfb7644164ec346328f12fb2f58958b03af26e1487d22352676d7e148972e

data/README.md

@@ -8,22 +8,22 @@ Work smart, not strong. This gem gives developers an easy to understand and easy
 So lets say you have a complex set of incoming data, say a JSON:API-specification compliant payload that contains the data to create an account on your server. Of course, your e-commerce platform is pretty flexible; You don't stop users from creating an account just because they don't have an email or password. So let's see how this would play out:
 
 ``` ruby
-class CreateAccountSchema
-  include SmartParams
-
-  schema do
-    field :data, subschema: true do
-      field :id, type: Coercible::String, nullable: true
-      field :type, type: Strict::String
-      field :attributes, subschema: true, nullable: true do
-        field :email, type: Strict::String, nullable: true
-        field :username, type: Strict::String, nullable: true
-        field :name, type: Strict::String, nullable: true
-        field :password, type: Strict::String.default { SecureRandom.hex(32) }, nullable: true
+module AccountSchema
+  include SmartParams::FluentLanguage
+
+  schema do |root|
+    field root, :data, subschema: true do |data|
+      field data, :id, type: Coercible::String.optional
+      field data, :type, type: Strict::String
+      field data, :attributes do |attributes|
+        field attributes, :email, type: Strict::String
+        field attributes, :username, type: Strict::String.optional
+        field attributes, :name, type: Strict::String.optional
+        field attributes, :password, type: Strict::String.default { SecureRandom.hex(32) }.optional
       end
     end
-    field :meta, Strict::Hash, nullable: true
-    field :included, type: Strict::Array, nullable: true
+    field :meta, Strict::Hash.optional
+    field :included, type: Strict::Array.optional
   end
 end
 ```
@@ -33,11 +33,11 @@ And now using that schema in the controller:
 ``` ruby
 class AccountsController < ApplicationController
   def create
-    schema = CreateAccountSchema.new(params)
+    payload = SmartParams.from(AccountSchema, params)
     # parameters will be a SmartParams::Dataset, which will respond to the various fields you defined
 
     # Here we're pulling out the id and data properties defined above
-    record = Account.create({id: schema.data.id, **schema.data.attributes})
+    record = Account.create({id: payload[:data][:id], **payload[:data][:attributes]})
 
     redirect_to account_url(record)
   end
@@ -49,43 +49,43 @@ Okay, so lets look at some scenarios.
 First, lets try an empty payload:
 
 ``` ruby
-CreateAccountSchema.new({})
-# raises SmartParams::Error::InvalidPropertyType, keychain: [:data], wanted: Hash, raw: nil
 
-# You can return the exception directly by providing :safe => false
+SmartParams.from(AccountSchema, {}).payload
+# returns [InvalidPropertyTypeException | MissingPropertyException]
 
-CreateAccountSchema.new({}, safe: false).payload
-# return #<SmartParams::Error::InvalidPropertyType... keychain: [:data], wanted: Hash, raw: nil>
+SmartParams.validate!(AccountSchema, {})
+# raises SmartParams::InvalidPayloadException(failures: [InvalidPropertyTypeException | MissingPropertyException])
 ```
 
 Great, we've told SmartParams we need `data` and it enforced this! The exception class knows the "key chain" path to the property that was missing and the value that was given. Lets experiment with that:
 
 ``` ruby
-CreateAccountSchema.new({data: ""})
-# raise SmartParams::Error::InvalidPropertyType, keychain: [:data], wanted: Hash, raw: ""
+SmartParams.from(AccountSchema, {data: ""})
+# returns [MissingPropertyException(path: [:data], last: {data: ""})]
 ```
 
 Sweet, we can definitely catch this and give the client a meaningful error! Okay, so to show off a good payload I'm going to do two things: Examine the properties and turn it to a JSON compatible structure. Lets see a minimum viable account according to our schema:
 
 
 ``` ruby
-schema = CreateAccountSchema.new({
+payload = SmartParams.from(AccountSchema, {
   data: {
-    type: "accounts"
+    type: "accounts",
+    attributes: {
+      email: "kurtis@example.com"
+    }
   }
 })
 
-schema.payload.data.type
+payload[:data][:type]
 # "accounts"
 
-schema.data.type
-# "accounts"
-
-schema.as_json
+payload.as_json
 # {
 #   "data" => {
 #     "type" => "accounts",
 #     "attributes" => {
+#       "email" => "kurtis@example.com",
 #       "password" => "1a6c3ffa4e96ad1660cb819f52a3393d924ac20073e84a9a6943a721d49bab38"
 #     }
 #   }

data/lib/smart_params/field.rb

@@ -2,156 +2,53 @@
 
 module SmartParams
   class Field
-    attr_reader :keychain
-    attr_reader :subfields
+    attr_reader :path
     attr_reader :type
-    attr_reader :nullable
-    attr_reader :key
 
-    def inspect
-      "#<#{self.class.name}:#{__id__} #{[
-        ('subschema' if @subschema),
-        ("#/#{@keychain.join('/')}" if @keychain),
-        ("-> #{type.name}" if @type),
-        ("= #{@value.inspect}" if @value)
-      ].compact.join(' ')}>"
-    end
-
-    def initialize(keychain:, type:, key: nil, subschema: false, nullable: false, &nesting)
-      @key = key
-      @keychain = Array(keychain)
-      @subfields = Set.new
+    def initialize(path:, type:, optional: false, **)
+      @path = path
       @type = type
-      @nullable = nullable
-      @subschema = subschema
-      @specified = false
-      @dirty = false
-
-      instance_eval(&nesting) if nesting
-
-      if subschema
-        @type = @type.schema(subfields.reduce({}) do |mapping, field|
-          mapping.merge("#{field.key}#{'?' if field.nullable}": field.type)
-        end).with_key_transform(&:to_sym)
+      @optional = !!optional
+    end
+
+    def map(raw)
+      case [*dig_until(@path, raw), @type, @type&.optional? || @optional]
+      in [:error, last, _, false]
+        [:error, SmartParams::MissingPropertyException.new(path:, last:)]
+      in [:error, _, _, true]
+        :skip
+      in [:ok, value, nil, _]
+        [:ok, value]
+      in [:ok, value, type, _]
+        type.try(value)
       end
-      @type = @type.optional if nullable
+    rescue Dry::Types::ConstraintError => constraint_error
+      Dry::Types::Result::Failure.new(value, constraint_error)
     end
 
-    def deep?
-      # We check @specified directly because we want to know if ANY
-      # subfields have been passed, not just ones that match the schema.
-      return false if nullable? && @specified
+    def update_in(result, value)
+      *body, butt = @path
 
-      subfields.present?
-    end
+      body.reduce(result) do |mapping, key|
+        mapping[key]
+      end.store(butt, value)
 
-    def root?
-      keychain.empty?
+      result
     end
 
-    def value
-      @value || ({} if root?)
-    end
-
-    def nullable?
-      !!@nullable
-    end
-
-    def specified?
-      if nullable?
-        !!@specified && clean?
-      else
-        !!@specified
-      end
-    end
-
-    # For nullable hashes: Any keys not in the schema make the hash dirty.
-    # If a key is found that matches the schema, we can consider the hash
-    # clean.
-    def dirty?
-      !!@dirty
-    end
-
-    def clean?
-      return false if dirty?
-      return true if empty? || subfields.reject(&:empty?).any?
-
-      false
-    end
-
-    # Check if we should consider this value even when empty.
-    def allow_empty?
-      return true if specified? && nullable?
-
-      subfields.any?(&:allow_empty?)
-    end
-
-    def claim(raw)
-      return type[dug(raw)] if deep?
-
-      @value = type[dug(raw)]
-    rescue Dry::Types::ConstraintError => _constraint_exception
-      raise SmartParams::Error::InvalidPropertyType.new(keychain:, wanted: type, raw: keychain.empty? ? raw : raw.dig(*keychain))
-    rescue Dry::Types::MissingKeyError => missing_key_exception
-      raise SmartParams::Error::InvalidPropertyType.new(keychain:, wanted: type, raw: keychain.empty? ? raw : raw.dig(*keychain), missing_key: missing_key_exception.key)
-    end
-
-    def to_hash
-      keychain.reverse.reduce(value) do |accumulation, key|
-        { key => accumulation }
-      end
-    end
-
-    def empty?
-      value.nil?
-    end
-
-    # Should this field be removed from resulting hash?
-    def removable?
-      empty? && !allow_empty?
-    end
-
-    def weight
-      keychain.map(&:to_s)
-    end
-
-    private def field(key, subschema: false, type: SmartParams::Hash, nullable: false, &subfield)
-      @subfields << self.class.new(key:, keychain: [*keychain, key], type:, nullable:, subschema:, &subfield)
-    end
-
-    private def subschema(key, nullable: false, &subfield)
-      field(key, subschema: true, type: SmartParams::Hash, nullable:, &subfield)
-    end
-
-    # Very busy method with recent changes. TODO: clean-up
-    private def dug(raw)
-      return raw if keychain.empty?
-
-      # If value provided is a hash, check if it's dirty. See #dirty? for
-      # more info.
-      if nullable?
-        hash = raw.dig(*keychain)
-        if hash.respond_to?(:keys)
-          others = hash.keys - [keychain.last]
-          @dirty = others.any?
+    private def dig_until(keychain, raw)
+      keychain.reduce([:ok, raw]) do |result, key|
+        case result
+        in [:ok, current]
+          if current.respond_to?(:key?) && current.key?(key)
+            [:ok, current[key]]
+          else
+            [:error, current]
+          end
+        in [:error, exception]
+          [:error, exception]
         end
       end
-
-      # Trace the keychain to find out if the field is explicitly set in the
-      # input hash.
-      at = raw
-      exact = true
-      keychain.each do |key|
-        if at.respond_to?(:key?) && at.key?(key)
-          at = at[key]
-        else
-          exact = false
-          break
-        end
-      end
-      @specified = exact
-
-      raw.dig(*keychain)
     end
   end
 end

data/lib/smart_params/fluent_language.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SmartParams
+  module FluentLanguage
+    extend ActiveSupport::Concern
+
+    included do
+      include Dry.Types()
+
+      mattr_accessor :namespaces
+    end
+
+    class_methods do
+      private def schema(namespace = :default)
+        self.namespaces ||= {}
+
+        raise SmartParams::NamespaceAlreadyDefinedException.new(namespace:) if self.namespaces.key?(namespace)
+
+        self.namespaces[namespace] = []
+
+        yield(namespace)
+
+        self.namespaces
+      end
+
+      private def field(prefix, name, type = nil, **)
+        raise MissingTypeException if type.nil? && !block_given?
+
+        root, *remaining = Kernel.Array(prefix)
+
+        path = [root, *remaining, name]
+
+        raise KeyAlreadyDefinedException.new(path:) if self.namespaces[root].any? { |field| field.path == path }
+
+        self.namespaces[root] = [
+          *self.namespaces[root],
+          SmartParams::Field.new(path: [*remaining, name], type:, subschema: block_given?, **)
+        ]
+
+        yield(path) if block_given?
+
+        self.namespaces[root]
+      end
+    end
+  end
+end

data/lib/smart_params/invalid_payload_exception.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SmartParams
+  class InvalidPayloadException < StandardError
+    attr_reader :failures
+
+    def initialize(failures:)
+      @failures = failures
+      super(message)
+    end
+
+    def message
+      "structure failed to validate: \n\t#{@failures.map(&:message).join("\n\t")}"
+    end
+  end
+end

data/lib/smart_params/invalid_property_type_exception.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SmartParams
+  class InvalidPropertyTypeException < StandardError
+    attr_reader :path
+    attr_reader :wanted
+    attr_reader :raw
+    attr_reader :type
+    attr_reader :grievance
+
+    def initialize(path:, wanted:, raw:, grievance:)
+      @path = path
+      @wanted = wanted
+      @raw = raw
+      @type = raw.inspect
+      @grievance = grievance
+      super(message)
+    end
+
+    def message
+      "expected /#{path.join('/')} to be #{wanted.name}, but is #{type} and #{grievance}"
+    end
+
+    def as_json
+      {
+        "path" => path,
+        "wanted" => wanted,
+        "grievance" => grievance,
+        "raw" => raw
+      }
+    end
+  end
+end

data/lib/smart_params/missing_property_exception.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SmartParams
+  class MissingPropertyException < StandardError
+    attr_accessor :path
+    attr_accessor :last
+
+    def initialize(path:, last:)
+      @path = path
+      @last = last
+      super(message)
+    end
+
+    def message
+      "/#{@path.join('/')} is missing from the structure, last node was #{@last.inspect}"
+    end
+  end
+end

data/lib/smart_params/namespace_already_defined_exception.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SmartParams
+  class NamespaceAlreadyDefinedException < StandardError
+    def initialize(namespace:)
+      @namespace = namespace
+      super(message)
+    end
+
+    def message
+      "#{@namespace} was already taken as a schema namespace"
+    end
+  end
+end

data/lib/smart_params/no_matching_namespace_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SmartParams
+  class NoMatchingNamespaceException < StandardError
+    def initialize(namespace:, available:)
+      @namespace = namespace
+      @available = available
+      super(message)
+    end
+
+    def message
+      "#{@namespace} does not exist, only #{@available.inspect}"
+    end
+  end
+end

data/lib/smart_params/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmartParams
-  VERSION = "5.1.0"
+  VERSION = "6.0.0"
 end

data/lib/smart_params.rb

@@ -1,108 +1,55 @@
 # frozen_string_literal: true
 
 require "dry-types"
-require "recursive-open-struct"
 require "active_support/concern"
 require "active_support/core_ext/object"
-require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/module"
 
 module SmartParams
-  extend ActiveSupport::Concern
-  include Dry.Types()
-
+  require_relative "smart_params/invalid_payload_exception"
+  require_relative "smart_params/invalid_property_type_exception"
+  require_relative "smart_params/missing_property_exception"
+  require_relative "smart_params/namespace_already_defined_exception"
+  require_relative "smart_params/no_matching_namespace_exception"
   require_relative "smart_params/field"
-  require_relative "smart_params/error"
-  require_relative "smart_params/version"
-
-  attr_reader :raw
-  attr_reader :schema
-  attr_reader :fields
-
-  def initialize(raw, safe: true, name: :default)
-    @safe = safe
-    @raw = raw
-    @schema = self.class.instance_variable_get(:@schema)[name]
-
-    @fields = [@schema, *unfold(@schema.subfields)].sort_by(&:weight).each { |field| field.claim(raw) }
-  rescue SmartParams::Error::InvalidPropertyType => invalid_property_exception
-    raise invalid_property_exception if safe?
-
-    @exception = invalid_property_exception
-  end
-
-  def inspect
-    "#<#{self.class.name}:#{__id__} @fields=#{@fields.inspect} @raw=#{@raw.inspect}>"
-  end
-
-  def payload
-    if @exception.present?
-      @exception
-    else
-      RecursiveOpenStruct.new(structure)
+  require_relative "smart_params/fluent_language"
+
+  def self.validate!(schema, raw, namespace = :default)
+    case map(fetch_namespace(schema, namespace), raw)
+    in [result, []]
+      result
+    in [_, failures]
+      raise InvalidPayloadException.new(failures:)
     end
   end
 
-  def to_hash(options = nil)
-    if @exception.present?
-      @exception.as_json(options)
-    else
-      structure.as_json(options) || {}
+  def self.from(schema, raw, namespace = :default)
+    case map(fetch_namespace(schema, namespace), raw)
+    in [result, []]
+      result
+    in [_, failures]
+      failures
     end
   end
-  alias as_json to_hash
 
-  delegate :[], to: :to_hash
-  delegate :fetch, to: :to_hash
-  delegate :fetch_values, to: :to_hash
-  delegate :merge, to: :to_hash
-  delegate :keys, to: :to_hash
-  delegate :key?, to: :to_hash
-  delegate :has_key?, to: :to_hash
-  delegate :values, to: :to_hash
-  delegate :value?, to: :to_hash
-  delegate :has_value?, to: :to_hash
-  delegate :dig, to: :to_hash
-  delegate :to_s, to: :to_hash
-
-  def respond_to_missing?(name, include_private = false)
-    payload.respond_to?(name) || super
-  end
-
-  def method_missing(name, *arguments, &)
-    if payload.respond_to?(name)
-      payload.public_send(name)
-    else
-      super
-    end
-  end
-
-  # This function basically takes a list of fields and reduces them into a tree of values
-  private def structure
-    fields
-      .reject(&:removable?)
-      .map(&:to_hash)
-      .reduce(&:deep_merge)
-  end
-
-  # This funcion takes a nested field tree and turns it into a list of fields
-  private def unfold(subfields)
-    subfields.to_a.reduce([]) do |list, field|
-      if field.deep?
-        [*list, field, *unfold(field.subfields.to_a)]
-      else
-        [*list, field]
+  private_class_method def self.map(fields, raw)
+    fields.reduce([Hash.new { |h, k| h[k] = h.class.new(&h.default_proc) }, []]) do |(result, failures), field|
+      case field.map(raw)
+      in :skip
+        [result, failures]
+      in [:ok, value]
+        [field.update_in(result, value), failures]
+      in Dry::Types::Result::Success => success
+        [field.update_in(result, success.input), failures]
+      in Dry::Types::Result::Failure => failure
+        [result, [*failures, InvalidPropertyTypeException.new(path: field.path, wanted: field.type, raw: failure.input, grievance: failure.error)]]
+      in [:error, value]
+        [result, [*failures, value]]
       end
-    end.flatten
-  end
-
-  private def safe?
-    @safe
+    end
   end
 
-  class_methods do
-    def schema(name: :default, &definitions)
-      @schema ||= {}
-      @schema[name] = Field.new(keychain: [], type: SmartParams::Hash, subschema: false, &definitions)
-    end
+  private_class_method def self.fetch_namespace(schema, namespace)
+    schema.namespaces[namespace] || raise(NoMatchingNamespaceException.new(namespace:, available: schema.namespaces.keys))
   end
 end