sorbet_typed-props 0.1.1

data/README.md

@@ -0,0 +1,131 @@
+# SorbetTyped::Props
+
+An extension of sorbets native props syntax, to make it usable and fully typed in any class. Mainly provides a tapioca
+dsl compiler to generate the initializer signature when using props outside of `T::Struct`.
+
+You can use the [`T::Struct` `props` and `const` syntax](https://sorbet.org/docs/tstruct) to define attributes on any
+class.
+
+This should make it easier to create classes with a set of attributes they should be initialized with. Inspiration was
+the
+[integration of literal properties into phlex](https://www.phlex.fun/miscellaneous/literal-properties.html#literal-properties),
+which doesn't really work with sorbet, if you want to have everything fully typed (and not use two runtime typesystems
+in parallel).
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add sorbet_typed-props
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install sorbet_typed-props
+```
+
+## Usage
+
+Include the `SorbetTyped::Props` module in any class you want to have `T::Struct`-like attributes:
+
+```ruby
+class MyClass
+  include SorbetTyped::Props
+
+  prop :my_prop, String
+end
+
+my_object = MyClass.new(my_prop: 'foo')
+
+my_object.my_prop # => "foo"
+my_object.my_prop = 'bar'
+```
+
+### Method Visibility
+
+If you want attributes in your initializer but not be part of your public class interface, you can use ruby's visibility
+modifiers. Unfortunately I found no better way and did not want to modify sorbet's prop syntax.
+
+```ruby
+class MyClass
+  extend T::Sig
+  include SorbetTyped::Props
+
+  prop :my_prop, Integer # reader and writer are public
+  const :my_const, String # reader ist public, has no writer
+
+  prop :prop_with_private_writer, String # reader is public, writer should be private
+  private :prop_with_private_writer= # makes the writer private
+
+  const :my_private_prop, String # reader and writer are private
+  private :my_private_prop, :my_private_prop=
+
+  sig { void }
+  def foo
+    self.prop_with_private_writer = 'foo'
+  end
+
+  sig { returns(String) }
+  def bar
+    self.my_private_prop
+  end
+
+  sig { void }
+  def baz
+    self.my_private_prop = 'baz'
+  end
+end
+
+my_object = MyClass.new(my_prop: 1, my_const: 'my_const', prop_with_private_writer: 'abc', my_private_prop: 'xyz')
+
+my_object.my_prop # => 1
+my_object.my_prop = 2
+
+my_object.my_const # => "my_const"
+my_object.my_const = 'abc' # => Setter method `my_const=` does not exist on `MyClass`
+
+my_object.prop_with_private_writer # => "abc"
+my_object.prop_with_private_writer = 'foo' # => Non-private call to private method `prop_with_private_writer=` on `MyClass`
+my_object.foo
+my_object.prop_with_private_writer # => "foo"
+
+my_object.my_private_prop # => Non-private call to private method `my_private_prop` on `MyClass`
+my_object.bar # => "xyz"
+my_object.my_private_prop = 'baz' # => Non-private call to private method `my_private_prop=` on `MyClass`
+my_object.baz
+my_object.bar # => "baz"
+```
+
+Putting prop-definition after an access modifier without arguments does not work:
+
+```ruby
+class MyClass
+  include SorbetTyped::Props
+
+  private
+
+  prop :my_prop, String # <= still public
+end
+```
+
+## Development
+
+The project uses [mise-en-place](https://mise.jdx.dev/) as development tool.
+
+After checking out the repo, run `mise run setup` to install dependencies. Then, run `mise test` to run the tests. You
+can also run `mise task ls` for a list of available tasks.
+
+RSpec is used as test suite. Spec files can and should be placed right beside their associated class files.
+
+<!-- WIP: develop and document release workflow -->
+
+<!-- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at
+[gitlab.com/sorbet_typed/props](https://gitlab.com/sorbet_typed/props).

data/lib/sorbet_typed/props/version.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SorbetTyped # rubocop:disable Style/ClassAndModuleChildren -- Disabled, because this file gets required in gemspec, where zeitwerk is not active
+  module Props
+    VERSION = '0.1.1'
+  end
+end

data/lib/sorbet_typed/props.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require_relative 'props/version'
+
+# an abstraction module to be included in any class to make the sorbet props
+# interface usable. It's just a wrapper around T::Props and
+# T::Props::Constructor. It's also the ancestor the custom tapioca compiler
+# looks for when generating initializer type annotation rbis.
+module SorbetTyped::Props
+  extend T::Helpers
+
+  include T::Props
+  include T::Props::Constructor
+
+  mixes_in_class_methods(T::Props::ClassMethods)
+end

data/lib/sorbet_typed/railway.rb.tmp

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require_relative 'railway/version'
+
+# This class provides a monad-style railway pattern, inspired by dry-monads do-syntax
+class SorbetTyped::Railway # rubocop:todo Lint/EmptyClass
+end

data/lib/sorbet_typed/railway.tmp/fail_fast.rb.tmp

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+class Typed::Monads::FailFast
+  extend T::Generic
+
+  Elem = type_member(:out)
+
+  sig { returns(Elem) }
+  attr_reader :value
+
+  sig { params(value: Elem).void }
+  def initialize(value)
+    @value = value
+  end
+end

data/lib/sorbet_typed/railway.tmp/railway.rb.tmp

@@ -0,0 +1,259 @@
+# typed: strict
+# frozen_string_literal: true
+
+# WIP: do we need https://sorbet.org/docs/exhaustiveness
+
+# WIP: move subclasses into own files
+
+# implementation of a sorbet-typed and -compatible monad-style short-circuit
+# pattern where you can run multiple steps, use their value OR let them return
+# early.
+#
+# Developed by @kramer and pending to be made open source under
+# https://gitlab.com/richardkramer/sorbet_typed. But for now we want to already
+# use the code, so everything already working is copied here.
+#
+# How to use:
+#
+
+# ```ruby
+# sig { returns(SuccessType, SorbetTyped::ShortCircuit::Shorted[ShortedType]))}
+# def do_something
+#   return SorbetTyped::ShortCircuit.short(info: shorted_value) if something_wrong?
+
+#   return SuccessType.new
+# end
+#
+# # this will return either the success type or a shorted result with the
+# # shorted type as `info`.
+# result = SorbetTyped::ShortCircuit[SuccessType, ShortedType].new.run do |circuit_breaker|
+#   foo = circuit_breaker.(do_something) # => will break early if do_something returns a circuit breaking result
+#   bar = circuit_breaker.(do_something_else(foo)) # => will break early if do_something_else(foo) returns a circuit breaking result
+
+#   do_another_thing(bar)
+# end
+# ```
+#
+# SuccessType and ShortedType might be anything you want. Just specify the types
+# when initializing the SorbetTyped::ShortCircuit instance.
+module SorbetTyped
+  class ShortCircuit
+    extend T::Generic
+
+    # The error thrown and handled within the run block to implement failing fast
+    # from any nesting depth
+    class CircuitShortedError < StandardError
+      extend T::Generic
+
+      FailureData = type_member(:out)
+
+      sig { returns(FailureData) }
+      attr_reader :failure
+
+      sig { params(failure: FailureData).void }
+      def initialize(failure:)
+        @failure = failure
+        super()
+      end
+    end
+
+    # Signal to fail fast. Info can be anything, e.g. an error object.
+    class Shorted
+      extend T::Generic
+
+      Elem = type_member(:out)
+
+      sig { returns(Elem) }
+      attr_reader :info
+
+      sig { params(info: Elem).void }
+      def initialize(info)
+        @info = info
+      end
+    end
+
+    # Callable implementing the logic to fail fast if the input is a Shorted
+    # signal. To be used like Dry::Monads `yield foo` syntax.
+    #
+    # Injected as parameter into a short circuit block, so you can use it directly.
+    class CircuitBreaker
+      extend T::Generic
+
+      Result = type_member
+
+      sig do
+        type_parameters(:U, :E).
+          params(result: T.all(T.type_parameter(:U), T.any(T.type_parameter(:E), Shorted[Result]))).
+          returns(T.type_parameter(:E))
+      end
+      def call(result)
+        case result
+        when Shorted
+          raise CircuitShortedError[T.type_parameter(:U)].new(failure: result)
+        else
+          result
+        end
+      end
+    end
+
+    SuccessResult = type_member
+    ShortedResult = type_member
+
+    sig do
+      type_parameters(:U).
+        params(info: T.type_parameter(:U)).
+        returns(Shorted[T.type_parameter(:U)])
+    end
+    def self.short(info:)
+      Shorted[T.type_parameter(:U)].new(info)
+    end
+
+    private
+
+    # Store if the last run failed fast
+    sig { returns(T::Boolean) }
+    attr_accessor :short_circuited
+
+    public
+
+    sig { void }
+    def initialize
+      @short_circuited = T.let(false, T::Boolean)
+    end
+
+    sig do
+      params(
+        _block:
+          T.proc.
+            params(fail_fast: CircuitBreaker[ShortedResult]).
+            returns(T.any(SuccessResult, Shorted[ShortedResult]))
+      ).
+        returns(T.any(SuccessResult, Shorted[ShortedResult]))
+    end
+    def run(&_block)
+      self.short_circuited = false
+      yield(CircuitBreaker[ShortedResult].new)
+    rescue CircuitShortedError => exception
+      self.short_circuited = true
+
+      # NOTE: sorbet is only able to detect
+      # `SorbetTyped::ShortCircuit::CircuitShortedError[T.anything]` in this rescue. But
+      # because it must come from `CircuitBreaker[ShortedResult]`, it will also
+      # always be `CircuitShortedError[SorbetTyped::ShortCircuit::Shorted[ShortedResult]]`. So we
+      # tell that to sorbet.
+      #
+      # NOTE: if one would manually throw this exception WITH A DIFFERENT failure
+      # data type, this would not raise, because generic types get erased at
+      # runtime. So just NEVER raise the CircuitShortedError error manually.
+      T.cast(exception, CircuitShortedError[SorbetTyped::ShortCircuit::Shorted[ShortedResult]]).failure
+    end
+
+    sig do
+      params(
+        block:
+          T.proc.
+            params(fail_fast: CircuitBreaker[ShortedResult]).
+            returns(T.any(SuccessResult, SorbetTyped::ShortCircuit::Shorted[ShortedResult]))
+      ).
+        returns(T.any(SuccessResult, ShortedResult))
+    end
+    def run_without_signal(&block)
+      result = run(&block)
+
+      case result
+      when SorbetTyped::ShortCircuit::Shorted
+        # NOTE: sorbet is only able to detect
+        # ```
+        #   T.all(
+        #     Typed::Monads::Shorted[T.anything],
+        #     T.any(
+        #       Typed::Monads::Shorted[Typed::Monads::ShortCircuit::ShortedResult],
+        #       Typed::Monads::ShortCircuit::SuccessResult
+        #     )
+        #   )
+        # ```
+        # , which leaves no other option
+        # than `Typed::Monads::Shorted[ShortedResult]`. So we tell that to the
+        # typechecker.
+        T.cast(result, SorbetTyped::ShortCircuit::Shorted[ShortedResult]).info
+      else
+        result
+      end
+    end
+
+    sig { returns(T::Boolean) }
+    def last_run_short_circuited?
+      short_circuited
+    end
+  end
+end
+
+#####################################################################################################################
+#####################################################################################################################
+#####################################################################################################################
+
+# An example class using above short circuit pattern. It's fully checked against
+# sorbet. You might comment it in and run `srb tc` to see the `T.reveal_type`
+# results in action.
+#
+# WIP: move to specs
+class SorbetTyped::ShortCircuitExample
+  extend T::Sig
+
+  sig { void }
+  def call
+    # Success Value might be Integer or String, Failure might be Symbol or Float
+    short_circuit = SorbetTyped::ShortCircuit[T.any(Integer, String), T.any(Symbol, Float)].new
+
+    result = short_circuit.run do |circuit_breaker|
+      T.reveal_type(circuit_breaker.(3)) # => Integer; sorbet knows the Input-Type would be the output type if it's not a Shorted signal
+
+      foo_var = circuit_breaker.(foo)
+
+      'bar'
+    end
+
+    short_circuit.last_run_short_circuited?
+    # => depends on the `[true, false].sample` below
+    #
+    # the `foo` call contains a shorted circuit, propagating the Shorted signal outwards and failing this circuit
+
+    T.reveal_type(result) # => T.any(Integer, String, SorbetTyped::Railway::Shorted[T.any(Symbol, Float)])
+
+    # the result might be any of the success type or the Shorted signal object
+    # with its shorted types. Use case...when logic to operate on the different
+    # return types.
+
+    if result.is_a? SorbetTyped::ShortCircuit::Shorted
+      T.reveal_type result # => SorbetTyped::Railway::Shorted[T.any(Symbol, Float)]
+      T.reveal_type result.info # => T.any(Symbol, Float); the for the railway defined shorted result types
+      puts result.info
+
+      # handle error
+      return
+    end
+
+    T.reveal_type(result)
+    # => T.any(Integer, String); sorbet statically knows, this can never be a shorted result, as we handled it before and return early
+  end
+
+  sig do
+    returns(T.any(Integer, SorbetTyped::ShortCircuit::Shorted[Symbol]))
+  end
+  def foo
+    SorbetTyped::ShortCircuit[Integer, Symbol].new.run do |circuit_breaker|
+      # this sometimes fast fails the short circuit and propagates the signal outwards
+      circuit_breaker.call validate # WIP: edge case where wrong typing does not raise errors in typechecker
+
+      42
+    end
+  end
+
+  sig { returns(T.any(NilClass, SorbetTyped::ShortCircuit::Shorted[Symbol])) }
+  def validate
+    return SorbetTyped::ShortCircuit.short(info: :foo) if [true, false].sample
+    return SorbetTyped::ShortCircuit.short(info: :bar) if [true, false].sample
+
+    SorbetTyped::ShortCircuit.short(info: :baz) if [true, false].sample
+  end
+end

data/lib/sorbet_typed/railway.tmp/version.rb.tmp

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SorbetTyped # rubocop:disable Style/ClassAndModuleChildren -- Disabled, because this file gets required in gemspec, where zeitwerk is not active
+  class Railway
+    VERSION = '0.1.0'
+  end
+end

data/lib/sorbet_typed/railway.tmp/version_spec.rb.tmp

@@ -0,0 +1,10 @@
+# typed: strict
+# frozen_string_literal: true
+
+RSpec.describe SorbetTyped::Railway do # rubocop:disable RSpec/SpecFilePathFormat
+  let(:version) { SorbetTyped::Railway::VERSION }
+
+  it 'has a version number' do
+    expect(version).not_to be_nil
+  end
+end

data/lib/sorbet_typed/railway_spec.rb.tmp

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+RSpec.describe SorbetTyped::Railway do # rubocop:todo Lint/EmptyBlock, RSpec/EmptyExampleGroup
+end

data/lib/tapioca/dsl/compilers/sorbet_typed_props_constructor/prop_to_param_converter.rb

@@ -0,0 +1,86 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Tapioca # rubocop:disable Style/ClassAndModuleChildren
+  module Dsl
+    module Compilers
+      class SorbetTypedPropsConstructor < Tapioca::Dsl::Compiler
+        # convert sorbet prop to rbi parameter
+        class PropToParamConverter
+          # representation of sorbet prop details
+          class Details < T::ImmutableStruct
+            # identifiable default value when the respective key was not passed to the struct deserializer
+            class ParamValueEnum < T::Enum # rubocop:disable Sorbet/MultipleTEnumValues -- an enum is an easy way to have an identifiable object without having to rely on it's value. Maybe there is another way, but I could not get it to work with a simple class and a constant would be value-bound.
+              enums do
+                ParamNotPresent = new
+              end
+            end
+
+            extend T::Sig
+
+            const :type_object, T::Types::Simple
+            const :_nilable, T::Boolean, default: false
+            const :default, Object, default: ParamValueEnum::ParamNotPresent
+            const :factory, Object, default: ParamValueEnum::ParamNotPresent
+
+            sig { returns(T::Boolean) }
+            def optional?
+              _nilable || default != ParamValueEnum::ParamNotPresent || factory != ParamValueEnum::ParamNotPresent
+            end
+          end
+
+          extend T::Sig
+          include Tapioca::RBIHelper
+
+          private
+
+          sig { returns(Symbol) }
+          attr_reader :name
+
+          sig { returns(Details) }
+          attr_reader :details
+
+          public
+
+          sig { params(name: Symbol, details: Details).void }
+          def initialize(name:, details:)
+            @name = name
+            @details = details
+          end
+
+          sig { returns(RBI::TypedParam) }
+          def create_rbi_parameter
+            if optional?
+              create_kw_opt_param(parameter_name, type:, default: 'nil')
+            else
+              create_kw_param(parameter_name, type:)
+            end
+          end
+
+          private
+
+          sig { returns(T::Boolean) }
+          def optional?
+            details.optional?
+          end
+
+          sig { returns(String) }
+          def type
+            details_type = details.type_object.name
+
+            if optional?
+              "T.nilable(#{details_type})"
+            else
+              details_type.to_s
+            end
+          end
+
+          sig { returns(String) }
+          def parameter_name
+            name.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/sorbet_typed_props_constructor.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'sorbet_typed_props_constructor/prop_to_param_converter'
+
+module Tapioca # rubocop:disable Style/ClassAndModuleChildren
+  module Dsl
+    module Compilers
+      # tapioca compiler generating rbi containing the initializer interface for a class using sorbet SorbetTyped::Props
+      class SorbetTypedPropsConstructor < Tapioca::Dsl::Compiler
+        extend T::Sig
+        extend T::Generic
+
+        ConstantType = type_member { { fixed: T.class_of(SorbetTyped::Props) } }
+
+        sig { override.returns(T::Enumerable[Module]) }
+        def self.gather_constants
+          # Collect all the classes that include SorbetTyped::Props
+          all_classes.select { |klass| klass < SorbetTyped::Props }
+        end
+
+        sig { override.void }
+        def decorate
+          # NOTE: do not generate a new initializer signature, if the class sets
+          # its own and doesn't use the prop generated one.
+          return if constant.private_instance_methods(false).include?(:initialize)
+
+          props = constant.props
+          return if props.empty?
+
+          params = params_from_props(props:)
+          define_initializer_sig(constant:, params:)
+        end
+
+        private
+
+        sig { params(props: T.untyped).returns(T::Array[RBI::TypedParam]) }
+        def params_from_props(props:)
+          props.map do |name, details|
+            create_param_from_prop(name:, details:)
+          end
+        end
+
+        sig { params(name: Symbol, details: T.untyped).returns(RBI::TypedParam) }
+        def create_param_from_prop(name:, details:)
+          details_struct =
+            Tapioca::Dsl::Compilers::SorbetTypedPropsConstructor::PropToParamConverter::Details.
+              from_hash(details.transform_keys(&:to_s))
+
+          Tapioca::Dsl::Compilers::SorbetTypedPropsConstructor::PropToParamConverter.
+            new(
+              name:,
+              details: details_struct
+            ).
+            create_rbi_parameter
+        end
+
+        # HACK: `T.class_of(SorbetTyped::Props)` fails when passed one of the
+        # anonymous test classes. But active typechecking isn't that relevant
+        # here.
+        sig { params(constant: T.class_of(SorbetTyped::Props), params: T::Array[RBI::TypedParam]).void.checked(:never) }
+        def define_initializer_sig(constant:, params:)
+          root.create_path(constant) do |klass|
+            klass.create_method(
+              'initialize',
+              parameters: params,
+              return_type: 'void',
+              comments: [RBI::Comment.new('Generated from sorbet SorbetTyped::Props')]
+            )
+          end
+        end
+      end
+    end
+  end
+end