sorbet-runtime 0.4.4969 → 0.4.4972

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f204f6d778bf65a3c81518f5ac3c2160b74f4bcd0ea73654285fa9561d7884
-  data.tar.gz: d897c48135338d0edaaf7562ca4de202c0c139e124d041bc29fb08485162107f
+  metadata.gz: 53211ac8c4d54178673a7fb13f499fea6e0808239266f249027303fedab70fb7
+  data.tar.gz: b5952024c57f88f975fb689e8b921b283eb4a20bf56b04380b6c8cf3236a968e
 SHA512:
-  metadata.gz: ce7b1756acfbc8a10b38550642a5f2af8bade745b80bb88dfe6278659f2a8d48589cd8b56d6a537f799d94098d91f817d3a96227223d1432f5ec342ded73c51d
-  data.tar.gz: dde92e7a96749903b11bd41485859200c06bed34de58b0cba887204560b9602838592baeb0964675ed5216e6f0887b400cee9f2248367dca945c2999086196fe
+  metadata.gz: f0aed40e7e7617d289e77544f30a2ed8335ea1a4480159b75194622cd777897c64630f417b9f35dc99571e9c8818e3e76f9227ea0ed90ba3625463524e3fc75a
+  data.tar.gz: 2f21287bacccc1557d1fb5c4c257c7c34259724e2306a5db27c98620841af4a643e004913a79f421ca2d760003cdf1b88081346c4c2b85184eeb5eef8582b90b

data/lib/sorbet-runtime.rb

@@ -99,6 +99,8 @@ require_relative 'types/props/constructor'
 require_relative 'types/props/pretty_printable'
 require_relative 'types/props/serializable'
 require_relative 'types/props/type_validation'
+
 require_relative 'types/struct'
+require_relative 'types/enum'
 
 require_relative 'types/compatibility_patches'

data/lib/types/configuration.rb

@@ -356,6 +356,7 @@ module T::Configuration
     String
     Symbol
     Time
+    T::Enum
   }).freeze
 
   def self.scalar_types
@@ -382,6 +383,15 @@ module T::Configuration
     end
   end
 
+  def self.enable_legacy_t_enum_migration_mode
+    @legacy_t_enum_migration_mode = true
+  end
+  def self.disable_legacy_t_enum_migration_mode
+    @legacy_t_enum_migration_mode = false
+  end
+  def self.legacy_t_enum_migration_mode?
+    @legacy_t_enum_migration_mode || false
+  end
 
   private_class_method def self.validate_lambda_given!(value)
     if !value.nil? && !value.respond_to?(:call)

data/lib/types/enum.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+# typed: strict
+
+# Enumerations allow for type-safe declarations of a fixed set of values.
+#
+# Every value is a singleton instance of the class (i.e. `Suit::SPADE.is_a?(Suit) == true`).
+#
+# Each value has a corresponding serialized value. By default this is the constant's name converted
+# to lowercase (e.g. `Suit::Club.serialize == 'club'`); however a custom value may be passed to the
+# constructor. Enum will `freeze` the serialized value.
+#
+# @example Declaring an Enum:
+#   class Suit < T::Enum
+#     enums do
+#       CLUB = T.let(new, Suit)
+#       SPADE = T.let(new, Suit)
+#       DIAMOND = T.let(new, Suit)
+#       HEART = T.let(new, Suit)
+#     end
+#   end
+#
+# @example Custom serialization value:
+#   class Status < T::Enum
+#     enums do
+#       READY = T.let(new('rdy'), Status)
+#       ...
+#     end
+#   end
+#
+# @example Accessing values:
+#   Suit::SPADE
+#
+# @example Converting from serialized value to enum instance:
+#   Suit.from_serialized('club') == Suit::CLUB
+#
+# @example Using enums in type signatures:
+#   sig {params(suit: Suit).returns(Boolean)}
+#   def is_red?(suit); ...; end
+#
+# WARNING: Enum instances are singletons that are shared among all their users. Their internals
+# should be kept immutable to avoid unpredictable action at a distance.
+class T::Enum
+  extend T::Sig
+  extend T::Props::CustomType
+
+  # TODO(jez) Might want to restrict this, or make subclasses provide this type
+  SerializedVal = T.type_alias {T.untyped}
+  private_constant :SerializedVal
+
+  ## Enum class methods ##
+  sig {returns(T::Array[T.experimental_attached_class])}
+  def self.values
+    if @values.nil?
+      raise "Attempting to access values of #{self.class} before it has been initialized." \
+        " Enums are not initialized until the 'enums do' block they are defined in has finished running."
+    end
+    @values
+  end
+
+  # Convert from serialized value to enum instance.
+  #
+  # Note: It would have been nice to make this method final before people started overriding it.
+  # Note: Failed CriticalMethodsNoRuntimeTypingTest
+  #
+  # @return [self]
+  # @raise [KeyError] if serialized value does not match any instance.
+  sig {overridable.params(serialized_val: SerializedVal).returns(T.experimental_attached_class).checked(:never)}
+  def self.from_serialized(serialized_val)
+    if @mapping.nil?
+      raise "Attempting to access serialization map of #{self.class} before it has been initialized." \
+        " Enums are not initialized until the 'enums do' block they are defined in has finished running."
+    end
+    res = @mapping[serialized_val]
+    if res.nil?
+      raise KeyError.new("Enum #{self} key not found: #{serialized_val.inspect}")
+    end
+    res
+  end
+
+  # Note: It would have been nice to make this method final before people started overriding it.
+  # @return [Boolean] Does the given serialized value correspond with any of this enum's values.
+  sig {overridable.params(serialized_val: SerializedVal).returns(T::Boolean)}
+  def self.has_serialized?(serialized_val)
+    if @mapping.nil?
+      raise "Attempting to access serialization map of #{self.class} before it has been initialized." \
+        " Enums are not initialized until the 'enums do' block they are defined in has finished running."
+    end
+    @mapping.include?(serialized_val)
+  end
+
+
+  ## T::Props::CustomType
+
+  # Note: Failed CriticalMethodsNoRuntimeTypingTest
+  sig {params(value: T.untyped).returns(T::Boolean).checked(:never)}
+  def self.instance?(value)
+    value.is_a?(self)
+  end
+
+  # Note: Failed CriticalMethodsNoRuntimeTypingTest
+  sig {params(instance: T.nilable(T::Enum)).returns(SerializedVal).checked(:never)}
+  def self.serialize(instance)
+    # This is needed otherwise if a Chalk::ODM::Document with a property of the shape
+    # T::Hash[T.nilable(MyEnum), Integer] and a value that looks like {nil => 0} is
+    # serialized, we throw the error on L102.
+    return nil if instance.nil?
+
+    if self == T::Enum
+      raise "Cannot call T::Enum.serialize directly. You must call on a specific child class."
+    end
+    if instance.class != self
+      raise "Cannot call #serialize on a value that is not an instance of #{self}."
+    end
+    instance.serialize
+  end
+
+  # Note: Failed CriticalMethodsNoRuntimeTypingTest
+  sig {params(mongo_value: SerializedVal).returns(T.experimental_attached_class).checked(:never)}
+  def self.deserialize(mongo_value)
+    if self == T::Enum
+      raise "Cannot call T::Enum.deserialize directly. You must call on a specific child class."
+    end
+    self.from_serialized(mongo_value)
+  end
+
+
+  ## Enum instance methods ##
+
+
+  sig {returns(T.self_type)}
+  def dup
+    self
+  end
+
+  sig {returns(T.self_type).checked(:tests)}
+  def clone
+    self
+  end
+
+  # Note: Failed CriticalMethodsNoRuntimeTypingTest
+  sig {returns(SerializedVal).checked(:never)}
+  def serialize
+    assert_bound!
+    @serialized_val
+  end
+
+  sig {params(args: T.untyped).returns(T.untyped)}
+  def to_json(*args)
+    serialize.to_json(*args)
+  end
+
+  sig {returns(String)}
+  def to_s
+    inspect
+  end
+
+  sig {returns(String)}
+  def inspect
+    "#<#{self.class.name}::#{@const_name || '__UNINITIALIZED__'}>"
+  end
+
+  sig {params(other: BasicObject).returns(T.nilable(Integer))}
+  def <=>(other)
+    case other
+    when self.class
+      self.serialize <=> other.serialize
+    else
+      nil
+    end
+  end
+
+
+  # NB: Do not call this method. This exists to allow for a safe migration path in places where enum
+  # values are compared directly against string values.
+  #
+  # Ruby's string has a weird quirk where `'my_string' == obj` calls obj.==('my_string') if obj
+  # responds to the `to_str` method. It does not actually call `to_str` however.
+  #
+  # See https://ruby-doc.org/core-2.4.0/String.html#method-i-3D-3D
+  sig {returns(String)}
+  def to_str
+    msg = 'Implicit conversion of Enum instances to strings is not allowed. Call #serialize instead.'
+    if T::Configuration.legacy_t_enum_migration_mode?
+      T::Configuration.soft_assert_handler(
+        msg,
+        storytime: {class: self.class.name},
+      )
+      serialize.to_s
+    else
+      raise NoMethodError.new(msg)
+    end
+  end
+
+  sig {params(other: BasicObject).returns(T::Boolean).checked(:never)}
+  def ==(other)
+    case other
+    when String
+      if T::Configuration.legacy_t_enum_migration_mode?
+        comparison_assertion_failed(:==, other)
+        self.serialize == other
+      else
+        false
+      end
+    else
+      super(other)
+    end
+  end
+
+  sig {params(other: BasicObject).returns(T::Boolean).checked(:never)}
+  def ===(other)
+    case other
+    when String
+      if T::Configuration.legacy_t_enum_migration_mode?
+        comparison_assertion_failed(:===, other)
+        self.serialize == other
+      else
+        false
+      end
+    else
+      super(other)
+    end
+  end
+
+  sig {params(method: Symbol, other: T.untyped).void}
+  private def comparison_assertion_failed(method, other)
+    T::Configuration.soft_assert_handler(
+      'Enum to string comparison not allowed. Compare to the Enum instance directly instead. See go/enum-migration',
+      storytime: {
+        class: self.class.name,
+        self: self.inspect,
+        other: other,
+        other_class: other.class.name,
+        method: method,
+      }
+    )
+  end
+
+
+  ## Private implementation ##
+
+
+  sig {params(serialized_val: SerializedVal).void}
+  private def initialize(serialized_val=nil)
+    raise 'T::Enum is abstract' if self.class == T::Enum
+    if !self.class.started_initializing?
+      raise "Must instantiate all enum values of #{self.class} inside 'enums do'."
+    end
+    if self.class.fully_initialized?
+      raise "Cannot instantiate a new enum value of #{self.class} after it has been initialized."
+    end
+
+    serialized_val = serialized_val.frozen? ? serialized_val : serialized_val.dup.freeze
+    @serialized_val = T.let(serialized_val, T.nilable(SerializedVal))
+    @const_name = T.let(nil, T.nilable(Symbol))
+  end
+
+  sig {returns(NilClass).checked(:never)}
+  private def assert_bound!
+    if @const_name.nil?
+      raise "Attempting to access Enum value on #{self.class} before it has been initialized." \
+        " Enums are not initialized until the 'enums do' block they are defined in has finished running."
+    end
+  end
+
+  sig {params(const_name: Symbol).void}
+  def _bind_name(const_name)
+    @const_name = const_name
+    @serialized_val = const_to_serialized_val(const_name) if @serialized_val.nil?
+    freeze
+  end
+
+  sig {params(const_name: Symbol).returns(String)}
+  private def const_to_serialized_val(const_name)
+    # Historical note: We convert to lowercase names because the majority of existing calls to
+    # `make_accessible` were arrays of lowercase strings. Doing this conversion allowed for the
+    # least amount of repetition in migrated declarations.
+    const_name.to_s.downcase.freeze
+  end
+
+  sig {returns(T::Boolean)}
+  def self.started_initializing?
+    @started_initializing = T.let(@started_initializing, T.nilable(T::Boolean))
+    @started_initializing ||= false
+  end
+
+  sig {returns(T::Boolean)}
+  def self.fully_initialized?
+    @fully_initialized = T.let(@fully_initialized, T.nilable(T::Boolean))
+    @fully_initialized ||= false
+  end
+
+  # Entrypoint for allowing people to register new enum values.
+  # All enum values must be defined within this block.
+  sig {params(blk: T.proc.void).void}
+  def self.enums(&blk)
+    raise "enums cannot be defined for T::Enum" if self == T::Enum
+    raise "Enum #{self} was already initialized" if @fully_initialized
+    raise "Enum #{self} is still initializing" if @started_initializing
+
+    @started_initializing = true
+
+    yield
+
+    @values = T.let(nil, T.nilable(T::Array[T.experimental_attached_class]))
+    @mapping = T.let(nil, T.nilable(T::Hash[SerializedVal, T.experimental_attached_class]))
+
+    # Freeze the Enum class and bind the constant names into each of the instances.
+    @mapping = {}
+    self.constants(false).each do |const_name|
+      instance = self.const_get(const_name, false)
+      if !instance.is_a?(self)
+        raise "Invalid constant #{self}::#{const_name} on enum. " \
+          "All constants defined for an enum must be instances itself (e.g. `Foo = new`)."
+      end
+
+      instance._bind_name(const_name)
+      serialized = instance.serialize
+      if @mapping.include?(serialized)
+        raise "Enum values must have unique serializations. Value '#{serialized}' is repeated on #{self}."
+      end
+      @mapping[serialized] = instance
+    end
+    @values = @mapping.values.sort.freeze
+    @mapping.freeze
+    @fully_initialized = true
+  end
+
+  sig {params(child_class: Module).void}
+  def self.inherited(child_class)
+    super
+
+    raise "Inheriting from children of T::Enum is prohibited" if self != T::Enum
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sorbet-runtime
 version: !ruby/object:Gem::Version
-  version: 0.4.4969
+  version: 0.4.4972
 platform: ruby
 authors:
 - Stripe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-02 00:00:00.000000000 Z
+date: 2019-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -78,6 +78,7 @@ files:
 - lib/types/boolean.rb
 - lib/types/compatibility_patches.rb
 - lib/types/configuration.rb
+- lib/types/enum.rb
 - lib/types/generic.rb
 - lib/types/helpers.rb
 - lib/types/interface_wrapper.rb