alchemrest 3.1.0

data/lib/alchemrest/transforms/loose_hash.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class LooseHash < Morpher::Transform
+      include Anima.new(:allow_additional_properties, :optional, :required)
+
+      KEY_MESSAGE = 'Missing keys: %<missing>s, Unexpected keys: %<unexpected>s'
+      PRIMITIVE   = Primitive.new(::Hash)
+
+      private_constant(*constants(false))
+
+      # Apply transformation to input
+      #
+      # @param [Object] input
+      #
+      # @return [Either<Error, Object>]
+      def call(input)
+        PRIMITIVE
+          .call(input)
+          .lmap { |e| lift_error(e) }
+          .bind { |o| reject_keys(o) }
+          .bind { |o| transform(o) }
+      end
+
+      private
+
+      def transform(input)
+        transform_required(input).bind do |required|
+          transform_optional(input).fmap(&required.public_method(:merge))
+        end
+      end
+
+      def transform_required(input)
+        transform_keys(required, input)
+      end
+
+      memoize def defaults
+        optional.map(&:value).product([nil]).to_h
+      end
+
+      def transform_optional(input)
+        transform_keys(
+          optional.select { |key| input.key?(key.value) },
+          input,
+        ).fmap(&defaults.public_method(:merge))
+      end
+
+      def transform_keys(keys, input)
+        success(
+          keys
+            .to_h do |key|
+              [
+                key.value,
+                coerce_key(key, input).from_right do |error|
+                  return failure(error)
+                end,
+              ]
+            end,
+        )
+      end
+
+      def coerce_key(key, input)
+        key.call(input.fetch(key.value)).lmap do |error|
+          error(input: input, cause: error)
+        end
+      end
+
+      def reject_keys(input)
+        keys = input.keys
+        unexpected = allow_additional_properties ? [] : (keys - allowed_keys)
+        missing    = required_keys - keys
+        unexpected_properties_exist = allow_additional_properties || unexpected.empty?
+
+        if unexpected_properties_exist && missing.empty?
+          success(input)
+        else
+          failure(
+            error(
+              input: input,
+              message: format(KEY_MESSAGE, missing: missing, unexpected: unexpected),
+            ),
+          )
+        end
+      end
+
+      memoize def allowed_keys
+        required_keys + optional.map(&:value)
+      end
+
+      memoize def required_keys
+        required.map(&:value)
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/money_transform.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class MoneyTransform < Morpher::Transform
+      include Concord.new(:unit)
+
+      private_constant(*constants(false))
+
+      def call(input)
+        case input
+          when Numeric
+            success(into_money(input))
+          else
+            failure_error(input)
+        end
+      end
+
+      private
+
+      def into_money(amount)
+        case unit
+          when :cents
+            Money.from_cents(amount)
+          when :dollars
+            Money.from_amount(amount)
+          else
+            raise "Invalid unit #{unit}"
+        end
+      end
+
+      def failure_error(input)
+        failure(
+          error(
+            message: "Expected: Numeric but got #{input.class}",
+            input: input,
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/number.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Number < Morpher::Transform
+      def call(input)
+        case input
+          when Numeric
+            success(input)
+          else
+            failure_error(input)
+        end
+      end
+
+      private
+
+      def failure_error(input)
+        failure(
+          error(
+            message: "Expected: Numeric but got #{input.class}",
+            input: input,
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/output_type.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    # A wrapper around other transforms that provides metadata about the return type of the transform.
+    # Note this does not do anything to actually enforce that return type, although we may want to change
+    # that in the future. It's main purpose is to provide metadata we can use to inspect the schema of
+    # an `Alchemrest::Data` class.
+    class OutputType < T::Struct
+      const :sorbet_type, T.any(Class, T::Types::Base)
+      const :constraints, T::Array[Alchemrest::Transforms::Constraint]
+
+      def self.simple(sorbet_type)
+        new(sorbet_type:, constraints: [])
+      end
+
+      def graph
+        graphs = graph_types.select { |type| has_graph?(type) }.map(&:graph)
+
+        if graphs.size == 1
+          graphs.sole
+        end
+      end
+
+      def with(args)
+        OutputType.new({ sorbet_type:, constraints: }.merge(args))
+      end
+
+      def ==(other)
+        sorbet_type == other.sorbet_type && constraints.to_set == other.constraints.to_set
+      end
+
+      private
+
+      def has_graph?(type)
+        type.respond_to?(:<=) && type < Data
+      end
+
+      def graph_types
+        recursively_unwrap_raw_type(sorbet_type)
+      end
+
+      def recursively_unwrap_raw_type(type)
+        current_types = case type
+        in T::Types::Simple
+          [type.raw_type]
+        in T::Types::TypedArray => array
+          [array.type]
+        in T::Types::Union => union
+          union.types
+        else
+          [type]
+        end
+
+        current_types.map { |current_type|
+          if current_type.instance_of?(T::Types::TypedArray) || current_type.instance_of?(T::Types::Simple)
+            recursively_unwrap_raw_type(current_type)
+          else
+            current_type
+          end
+        }.flatten
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/to_decimal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class ToDecimal < Morpher::Transform
+      def call(input)
+        success(BigDecimal(input, 0))
+      rescue TypeError, ArgumentError
+        cannot_make_decimal(input)
+      end
+
+      def cannot_make_decimal(input)
+        failure(
+          error(
+            message: "Expected #{input} to be castable to BigDecimal",
+            input:,
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/to_type/from_string_to_time_selector.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class ToType
+      class FromStringToTimeSelector < TransformsSelector
+        def initialize(from)
+          super(from, nil, {})
+        end
+
+        def using(timezone_identifier, require_offset: true)
+          use, to = case timezone_identifier
+          in :utc
+            [[IsoTime.new(to_timezone: 'UTC', require_offset:)], ActiveSupport::TimeWithZone]
+          in :local
+            [[IsoTime.new(to_timezone: Time.zone.name, require_offset:)], ActiveSupport::TimeWithZone]
+          in :offset
+            raise ArgumentError, "require_offset cannot be false when using :offset" unless require_offset
+
+            [[IsoTime.new(to_timezone: nil, require_offset: true)], Time]
+          in String
+            [[IsoTime.new(to_timezone: timezone_identifier, require_offset:)], ActiveSupport::TimeWithZone]
+          end
+          ToType.new(from:, to:, use:)
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/to_type/transforms_selector.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class ToType
+      class TransformsSelector
+        INVALID_KEY_OR_TRANSFORM_ERROR_MESSAGE = "Must provide a symbol key or a Morpher::Transform"
+        INVALID_TRANSFORMS_HASH_ERROR_MESSAGE = "transform_options must a Hash with symbol keys, and values of Morpher::Transform[]"
+
+        include Concord.new(:from, :to, :transform_options)
+
+        def initialize(*)
+          super
+          unless transform_options_valid?
+            raise ArgumentError, INVALID_TRANSFORMS_HASH_ERROR_MESSAGE
+          end
+        end
+
+        def using(key_or_transform)
+          raise ArgumentError, INVALID_KEY_OR_TRANSFORM_ERROR_MESSAGE unless a_symbol_or_transform?(key_or_transform)
+
+          transforms_to_use = resolve_transforms_array(key_or_transform)
+
+          unless transforms_to_use
+            raise NoTransformOptionForNameError.new(from:, to:, name: key_or_transform, options: transform_options)
+          end
+
+          ToType.new(from:, to:, use: transforms_to_use)
+        end
+
+        def options
+          transform_options.keys
+        end
+
+        private
+
+        def transform_options_valid?
+          transform_options.instance_of?(Hash) &&
+            transform_options.keys.all?(Symbol) &&
+            transform_options.values.all? { |value| transform_array?(value) }
+        end
+
+        def a_symbol_or_transform?(value)
+          value.instance_of?(Symbol) || value.is_a?(Morpher::Transform)
+        end
+
+        def transform_array?(value)
+          value.instance_of?(Array) && value.all?(Morpher::Transform)
+        end
+
+        def resolve_transforms_array(value)
+          if value.is_a?(Morpher::Transform)
+            [value]
+          elsif transform_options.key?(value)
+            transform_options.fetch(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/to_type.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    # A class for taking in an input and transforming it so something else. To initialize this class
+    # you must provide a `FromType` transform that first validates that the input is actually transformable
+    # (via the `from:` param) and an array of transforms that will actualy do the transformation
+    # (via the `use:` param) If you want to run additional validations after transformation, you can use the `#where` method.
+    class ToType < Morpher::Transform
+      include Alchemrest::Transforms::Constrainable.new(additional_attributes: %i(to from use))
+      DEFAULTS = { constraints: [] }.freeze
+
+      def self.using(args, &block)
+        new(**args, use: [Success.new(block)])
+      end
+
+      def initialize(args)
+        super(**DEFAULTS.merge(args))
+
+        raise ArgumentError, ":to must be a Class" unless to.instance_of?(Class)
+        raise ArgumentError, ":from must be a FromType transform" unless from.is_a?(FromType)
+
+        unless use.instance_of?(::Array) && !use.empty? && use.all?(Morpher::Transform)
+          raise ArgumentError, ":use must be an array of Morpher::Transform instances"
+        end
+      end
+
+      def output_type
+        OutputType.new(sorbet_type: to, constraints: all_constraints)
+      end
+
+      def using(transforms)
+        with(use: transforms)
+      end
+
+      def call(input)
+        transform.call(input)
+      end
+
+      def all_constraints
+        [*from.constraints, *constraints]
+      end
+
+      def constraints_for(type)
+        raise ArgumentError, "Must provide a Class" unless type.instance_of?(Class)
+
+        unless [self, from].map { |transform| transform.output_type.sorbet_type }.include?(type)
+          raise ArgumentError,
+            "`type` must be either the to type (#{output_type.sorbet_type}) or the " \
+            "from type (#{from.output_type.sorbet_type}), was #{type}"
+        end
+
+        [self, from].select { |transform| transform.output_type.sorbet_type == type }.flat_map(&:constraints)
+      end
+
+      def array
+        Typed.new(transform: super(), output_type: output_type.with(sorbet_type: T::Array[(output_type.sorbet_type)]))
+      end
+
+      def maybe
+        Typed.new(transform: super(), output_type: output_type.with(sorbet_type: T.nilable(output_type.sorbet_type)))
+      end
+
+      private
+
+      def transform
+        Sequence.new([
+          from,
+          *use,
+          validate_output,
+          validate_constraints,
+        ])
+      end
+
+      def validate_output
+        Block.capture("Alchemrest::Transform::ToType") do |current|
+          if current.is_a?(to)
+            success(current)
+          else
+            failure("Transform chain created an ouput of type: #{current.class}. Expected: #{to}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/typed.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    # A wrapper around other transforms that provides metadata about the return type of the transform.
+    # Note this does not do anything to actually enforce that return type, although we may want to change
+    # that in the future. It's main purpose is to provide metadata we can use to inspect the schema of
+    # an `Alchemrest::Data` class.
+    class Typed < Morpher::Transform
+      include Anima.new(:transform, :output_type)
+      include Adamantium::Mutable
+
+      def call(input)
+        transform.call(input)
+      end
+
+      def array
+        Typed.new(
+          transform: super(),
+          output_type: output_type.with(sorbet_type: T::Array[output_type.sorbet_type]),
+        )
+      end
+
+      def maybe
+        Typed.new(
+          transform: super(),
+          output_type: output_type.with(sorbet_type: T.nilable(output_type.sorbet_type)),
+        )
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/union.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class Union < Morpher::Transform
+      include Anima.new(:types, :discriminator)
+
+      private_constant(*constants(false))
+
+      def call(input)
+        type_key = input&.fetch(discriminator.to_s)
+        if type_key.nil?
+          klass_not_found_failure_error(input)
+        else
+          perform_transformation(input, type_key)
+        end
+      end
+
+      def output_type
+        OutputType.simple(T.any(*types.values))
+      end
+
+      private
+
+      def perform_transformation(input, type_key)
+        klass = types[type_key.to_sym]
+        if klass
+          klass::TRANSFORM.call(input)
+        else
+          klass_not_found_failure_error(input)
+        end
+      end
+
+      def klass_not_found_failure_error(input)
+        failure(
+          error(
+            message: "Expected discriminator #{discriminator} to produce a value which is one of #{types.keys.join(',')} but got #{input&.fetch(discriminator).nil? ? 'nil' : input[discriminator]}", # rubocop:disable Layout/LineLength
+            input: input,
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms/with_constraint.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  module Transforms
+    class WithConstraint < Morpher::Transform
+      MESSAGE = %(Input %<actual>p does not meet the constraint "%<description>s")
+      include Concord.new(:constraint)
+
+      def initialize(constraint)
+        raise ArgumentError, "Must provide an instance of Alchemrest::Transform::Constraint" unless constraint.is_a?(Constraint)
+
+        super
+      end
+
+      def call(input)
+        if constraint.meets_conditions?(input)
+          success(input)
+        else
+          failure(
+            error(input:, message: format(MESSAGE, actual: input, description: constraint.description)),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/alchemrest/transforms.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Alchemrest
+  # The Transforms module is passed into the block provided to `Alchemrest::Data.schema`, giving developers an easy way to
+  # define the transforms for a given data class
+  #
+  # @example Using `Alchemrest::Transforms` inside a `schema` block
+  #   class User < Alchemrest::Data
+  #     schema do |s|
+  #       # `s` is `Alchemrest::Transforms`
+  #     end
+  #   end
+  module Transforms
+    # A transformation that results in an integer number. Must be a true integer in JSON, not a string as number. Will
+    # result in a `Alchemrest::MorpherTransformError` if not an integer number.
+    def self.integer
+      Typed.new(transform: Morpher::Transform::INTEGER, output_type: OutputType.simple(Integer))
+    end
+
+    # A transformation that results in a string. Must be a true string in JSON, we will not coerce booleans or number to strings. Will
+    # result in a `Alchemrest::MorpherTransformError` if not a string.
+    def self.string
+      Typed.new(transform: Morpher::Transform::STRING, output_type: OutputType.simple(String))
+    end
+
+    # A transformation that results in a float. Must be a float in JSON, we will coerce strings into numbers. Will
+    # result in a `Alchemrest::MorpherTransformError` if not a float. Note, if the api sometimes returns a float and
+    # sometimes returns an integer, see {#number} instead.
+    def self.float
+      Typed.new(transform: Morpher::Transform::FLOAT, output_type: OutputType.simple(Float))
+    end
+
+    def self.from
+      FromChain
+    end
+
+    # A transformation that results in some kind of numeric type, generally either a Float or Integer. If the input is not
+    # Numeric, will result in a `Alchemrest::MorpherTransformError`
+    def self.number
+      Typed.new(transform: Number.new, output_type: OutputType.simple(T.any(Float, Integer)))
+    end
+
+    # A transformation that results in a boolean. If the input is not a boolean, will result in a `Alchemrest::MorpherTransformError`
+    def self.boolean
+      Typed.new(transform: Morpher::Transform::BOOLEAN, output_type: OutputType.simple(T::Boolean))
+    end
+
+    # A transformation that results in a Date object.
+    # If the input is not an iso8601 date string, will result in a `Alchemrest::MorpherTransformError`
+    def self.date
+      Typed.new(transform: DateTransform.new, output_type: OutputType.simple(Date))
+    end
+
+    # A transformation that creates a {Money} object. You can indicate
+    # whether the original amount is in dollars our cents via the unit
+    # param. If the original value is not numeric, it will result in a
+    # `Alchemrest::MorpherTransformError`
+    #
+    # @param [Symbol] (:dollars | :cents) the unit for the original amount
+    def self.money(unit)
+      Typed.new(transform: MoneyTransform.new(unit), output_type: OutputType.simple(Money))
+    end
+
+    # A transformation that results in a {Symbol, String} from a predefined list.
+    # If the original value is not a string from the predefined list, it will
+    # result in a `Alchemrest::MorpherTransformError`
+    #
+    # @param [Array<Symbol>] the list of valid values for the field
+    def self.enum(enum)
+      Typed.new(transform: Enum.new(enum), output_type: OutputType.simple(T.any(Symbol, String)))
+    end
+
+    # A transformation that results in an Alchemrest::Data class. You can
+    # either provide a klass or a Hash with a `discriminator` value for
+    # polymorphic data types
+    #
+    # @param [Class, Hash<Symbol, Class>] Either an `Alchemrest::Data` class,
+    #        or a hash of classes along with a `discriminator` key for polymorphic
+    #        use cases
+    def self.one_of(klass_or_hash)
+      if klass_or_hash.instance_of? Hash
+        klasses = klass_or_hash.except(:discriminator)
+        Union.new(types: klasses, discriminator: klass_or_hash.fetch(:discriminator))
+      else
+        klass_or_hash::TRANSFORM
+      end
+    end
+
+    def self.many_of(klass)
+      klass::TRANSFORM.array
+    end
+  end
+end

data/lib/alchemrest/url_builder/encoders.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module Alchemrest
+  class UrlBuilder
+    module Encoders
+      def self.find(name)
+        case name
+        in :rack
+          RackEncoded.new
+        in :form
+          FormUrlEncoded.new
+        end
+      end
+
+      class RackEncoded
+        def call(query)
+          Rack::Utils.build_nested_query(query)
+        end
+      end
+
+      class FormUrlEncoded
+        def call(query)
+          URI.encode_www_form(query)
+        end
+      end
+
+      class Custom
+        def initialize(&block)
+          @block = block
+        end
+
+        def call(query)
+          @block.call(query)
+        end
+      end
+    end
+  end
+end