dry-types-tuple 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e6edbbb2c8dc709f36d3cfcdd63bab007411ad71106549f9a25986588d1d0af
-  data.tar.gz: 0fde381de860f1aa66dd3e35df16f611ea28cafbab83e45c75eae19b5452f0a4
+  metadata.gz: 7583440f28dfcf7be606ffade7d58fe0fac29e783c4b79eeb15467ff6b63c654
+  data.tar.gz: 27da3385c06793c20d7ece1872d740ebc9cc431dc795c9a3141de4a5d64314ee
 SHA512:
-  metadata.gz: 11393c3bd16005e8fca81b0b9e6483a8708f2bd7274f4f01eb70c0761ff2480492efd65bc332963b6c5c4c25698c9d9533ba2030407778e7ecc83279afe3185f
-  data.tar.gz: 233646bf141f872a84a011090fd3802678b88439662ec78e536fa08ead8c637aa203b22022f3f7e400fe7dc19c44a0565da5d40fe29a1381cfd22811ab45b8e0
+  metadata.gz: 1886d2dabab95dc8d07ba7285991b73e70bd6083d81280c0e2ec6dd3238e20889d4a186edc012d8e381523906b6d730f2782e285112ce17385c0db33e5003594
+  data.tar.gz: 4e6f489907102ca633736d9109725a96bcae2d677b25feca5daead2d3f69e32368410006325c3776c6e6196ea5dd0e9ff7b3126d5fd3776dc5f07e3d747a4051

data/Gemfile

@@ -13,6 +13,9 @@ group :test do
   gem "rspec"
   gem "warning"
   gem "rspec-instafail", require: false
+  gem "dry-initializer", require: false
+  gem "dry-inflector"
+  gem "dry-struct"
 end
 
 group :tools do

data/README.md

@@ -58,6 +58,83 @@ Dry::Types['tuple'].of \
   [Dry::Types['float'] | Dry::Types['integer']]
 ```
 
+### Class interface mixins
+
+The extra feature of the gem is tuple class interfaces mixins under the `Dry::Tuple` namespace. It isn't loaded by default,
+so it's dependent on `require "dry/tuple"`.
+
+#### Class interface for PORO-classes
+
+The interfaces provide a way to use a tuple in constructors to match proper class by input.
+The behaviour is similar to the one provided by `Dry::Struct::ClassInterface` and
+allows to combine classes into sums but with positional input validation & coercion.
+
+To do so, extend the class with `Dry::Tuple::ClassInterface` mixin and then assign an
+explicit tuple type by calling `tuple(type_declation)` method.
+
+With a couple of extended classes you will be able to compose a summing object, which
+could be used to match incoming values by tuples. When input matches any of summed
+tuples, it yields thru the type, performing coercions if need, but a top-level structure
+of input keeps to be an Array. There are two abstract class methods — `coerce_tuple` and
+`new_from_tuple`, — that could be redefined when, i.e., you need to splat an incoming
+array into arguments due to avoid breaking the existing interface.
+
+```ruby
+class Example
+  extend Dry::Tuple::ClassInterface
+  tuple Types.Tuple(Types.Value(:example) << Types::Coercible::Symbol, Types::String)
+
+  def initializer(left, right)
+    @left, @right = left, right
+  end
+
+  # @note Used by {StructClassInterface} under the hood.
+  # @param input [Array] after sub types coercion
+  # @return [Any] args acceptable by {#initializer}.
+  # def self.coerce_tuple(input)
+  #   input
+  # end
+
+  # @param input [Any] after {.coerce_tuple}
+  # @return [self] instantiated object with the given arguments
+  def self.new_from_tuple(input)
+    new(*input)
+  end
+end
+
+class OtherExample < Example
+  tuple Types.Tuple(Types.Value(:other_example) << Types::Coercible::Symbol, [Types::Any])
+
+  def initializer(left, right, *rest)
+    super(left, right)
+    @rest = rest
+  end
+end
+
+ExampleSum = Example | OtherExample
+ExampleSum[['example', 'foo']]
+# => #<Example @left = :example, @right = 'foo'>
+
+ExampleSum[['other_example', 1, '2', {}]].class
+# => #<Example @left = :other_example, @right = 1, @rest = ['2', {}]>
+```
+
+#### Class interface for Dry::Struct classes.
+
+And, the initial target of this gem, — let `Dry::Struct` classes to take both the key-value and
+the tuple inputs. Extend `Dry::Struct` classes with the `Dry::Tuple::StructClassInterface`,
+ensure keys order with helper method `auto_tuple *keys` (it will auto-declare the tuple from the struct's schema)…
+Profit!
+
+```ruby
+class SomeStruct < Dry::Struct
+  attribute :some, Types::Integer
+  attribute :with, Types::Hash
+  extend ::Dry::Tuple::StructClassInterface
+  auto_tuple :some, :with
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/dry-types-tuple.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "dry-types-tuple"
-  spec.version = '0.0.2'
+  spec.version = '0.1.0'
   spec.authors = ["Anton"]
   spec.email = ["anton.estum@gmail.com"]
 

data/lib/dry/tuple.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'dry/types/tuple'
+
+module Dry
+  # The namespace contains mixins for class decoration with tuple type.
+  # The interfaces provide a way to use a tuple in constructors to match proper class by input.
+  # The behaviour is similar to the one provided by `Dry::Struct::ClassInterface` and
+  # allows to combine classes into sums but with positional input validation & coercion.
+  #
+  # @example Splat input
+  #   class Example
+  #     extend Dry::Tuple::ClassInterface
+  #     tuple Types.Tuple(Types::Integer, Types::String)
+  #
+  #     def initializer(a1, a2)
+  #       # ...
+  #     end
+  #
+  #     def self.new_from_tuple(input)
+  #       new(*input)
+  #     end
+  #   end
+  module Tuple
+    # Pure class type decorator mixin.
+    module ClassDecorator
+      include Types::Decorator
+
+      # @return [@tuple]
+      def type
+        @tuple
+      end
+
+      # @param input [Array] the result of {#coerce_tuple}
+      # @return [self]
+      # @abstract
+      #   It is designed to be redefined for example to splat arguments on constructor.
+      # @note
+      #   Will be invoked on input that was passed thru tuple validation & coercion.
+      def new_from_tuple(input)
+        defined?(super) ? super(input) : new(input)
+      end
+
+      # @param input [Array] the result of tuple#call
+      # @return [Array] coerced input
+      # @note
+      #   Will be invoked on input that was passed thru tuple validation & coercion.
+      def coerce_tuple(input)
+        defined?(super) ? super(input) : input
+      end
+
+      # @api private
+      def call_safe(input, &block)
+        if defined?(super)
+          resolve_tuple_safe(input) { |output| super(output) }
+        elsif input.is_a?(self)
+          input
+        else
+          resolve_tuple_safe(input, &block)
+        end
+      end
+
+      # @api private
+      def call_unsafe(input)
+        if defined?(super)
+          resolve_tuple_safe(input) { |output| super(output) }
+        elsif input.is_a?(self)
+          input
+        else
+          resolve_tuple_unsafe(input)
+        end
+      end
+
+      private
+
+      # @api private
+      def resolve_tuple_safe(input)
+        input = tuple.call_safe(input) do |output = input|
+          output = yield(output) if block_given?
+          return output
+        end
+        new_from_tuple(coerce_tuple(input))
+      end
+
+      # @api private
+      def resolve_tuple_unsafe(input)
+        input = tuple.call_unsafe(input)
+        new_from_tuple(coerce_tuple(input))
+      end
+    end
+
+    module HookExtendObject
+      # Makes the module's features to be prepended instead of appended to the target class when extended.
+      # Also defines the `tuple` class attribute.
+      # @api private
+      private def extend_object(base)
+        base.singleton_class.prepend(self)
+        base.defines :tuple
+      end
+    end
+
+    module ClassInterface
+      include Core::ClassAttributes
+      include Types::Type
+      include Types::Builder
+      include ClassDecorator
+      extend HookExtendObject
+    end
+
+    # Extracted due to make it possible to use this feature within {Dry::Struct} classes.
+    # @example extending Dry::Struct subclass
+    #
+    #   class SomeStruct < Dry::Struct
+    #     attribute :some, Types::Integer
+    #     attribute :with, Types::Hash
+    #     extend ::Dry::Tuple::StructClassInterface
+    #     auto_tuple :some, :with
+    #   end
+    module StructClassInterface
+      include ClassDecorator
+      extend HookExtendObject
+
+      class << self
+        private def extend_object(base)
+          super
+          base.defines :keys_order
+          base.keys_order []
+        end
+      end
+
+      def auto_tuple(*keys)
+        keys_order(keys_order | keys)
+        index = schema.keys.map { |t| [t.name, t.type] }.to_h
+        tuple Dry::Types::Tuple.build_unsplat(index.values_at(*keys_order))
+      end
+
+      def coerce_tuple(input)
+        keys_order.zip(input).to_h
+      end
+    end
+  end
+end

data/lib/dry/types/tuple.rb

@@ -18,6 +18,11 @@ module Dry
       # @see build_index
       # @return [Dry::Types::Tuple]
       def self.build(*types)
+        build_unsplat(types)
+      end
+
+      # @api private
+      def self.build_unsplat(types)
         new(::Array, types_index: build_index(types))
       end
 
@@ -41,7 +46,7 @@ module Dry
         end
 
         if types[-1].size > 1
-          raise ArgumentError, "rest_type should be an Array with single element to apply to the rest of items"
+          raise ArgumentError, "rest_type should be an Array with single element to apply to the rest of items: #{types[-1]}"
         end
 
         types.pop[0]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-types-tuple
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Anton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-26 00:00:00.000000000 Z
+date: 2023-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -96,6 +96,7 @@ files:
 - README.md
 - Rakefile
 - dry-types-tuple.gemspec
+- lib/dry/tuple.rb
 - lib/dry/types/tuple.rb
 homepage: https://github.com/estum/dry-types-tuple
 licenses: