union-type 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edfcd1ae4c61f2097f644de21b2403419afc6c121d751823de6018a00975b921
-  data.tar.gz: a70a742afc27d29e14b62f420f00cee5bd97b8a97a736a577a566846e422af0c
+  metadata.gz: df57236a684d1ebd848590bf182f721c445dc23e3baeaa0b64e94fdccf8eac5b
+  data.tar.gz: 98a0c1d10cc84f2288cb9f19c573b1d180fd548d0c7a6fbfda3a317b9db188ad
 SHA512:
-  metadata.gz: ce9eaa5d32bf49436f52697773c6ab38aadbda78f27749602d8dda4b13ee87e6f3b5a7fa0c232df7b5a9444257b9304297a0d7401d1b09b04baf1f1cac42d597
-  data.tar.gz: e3f0954b10a66a9577ae019017c607def1d9af198d2679211c592d0a26416d158510ea5ee7b5539c891dc41c103a9ec62b21611a74165b0afaaf0bb6b0cc35d5
+  metadata.gz: bcbda94716e0b6556ca8c7933ebfc3e0ed89eb237045485f6d1124e312b3bb889afa2f709f09c43ef028e1ad06378ea92c24642c796326076eb0fc50c42c03bf
+  data.tar.gz: cff63507e647111edef948440d1f0a959f37070c6d136e2d0931cfc9ab6b05196b65a306b1fd92c69964bdef758fedfd82f381be821aeec1721872d5e77817ca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Gusiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/union_type/core_ext.rb

@@ -1,4 +1,14 @@
 class Class
+  # Returns a {UnionType} combining +self+ and +other+.
+  # Enables the +String | Integer+ literal syntax.
+  #
+  # @param other [Class, UnionType]
+  # @return [UnionType]
+  # @raise [TypeError] if +other+ is not a {Class} or {UnionType}
+  #
+  # @example
+  #   String | Integer          # => UnionType(Integer | String)
+  #   String | Integer | Float  # => UnionType(Float | Integer | String)
   def |(other)
     case other
     when Class
@@ -15,11 +25,31 @@ class Object
   alias_method :__is_a__?, :is_a?
   alias_method :__instance_of__?, :instance_of?
 
+  # Returns +true+ if this object is an instance of any class in the union.
+  # Falls back to the standard +is_a?+ for plain {Class} or {Module} arguments.
+  #
+  # @param type [Class, Module, UnionType]
+  # @return [Boolean]
+  #
+  # @example
+  #   "hello".is_a?(String | Integer)  # => true
+  #   42.is_a?(String | Integer)       # => true
+  #   :sym.is_a?(String | Integer)     # => false
   def is_a?(type)
     type.__is_a__?(UnionType) ? type === self : __is_a__?(type)
   end
   alias kind_of? is_a?
 
+  # Returns +true+ if this object's exact class is one of the union's members.
+  # Unlike {#is_a?}, subclass membership does not satisfy this check.
+  # Falls back to the standard +instance_of?+ for plain {Class} arguments.
+  #
+  # @param type [Class, UnionType]
+  # @return [Boolean]
+  #
+  # @example
+  #   42.instance_of?(Integer | String)  # => true
+  #   42.instance_of?(Numeric | String)  # => false (42 is not exactly Numeric)
   def instance_of?(type)
     type.__is_a__?(UnionType) ? type.include?(self.class) : __instance_of__?(type)
   end

data/lib/union_type/union_type.rb

@@ -1,8 +1,29 @@
 require "sorted_set"
 
+# A union type that matches values belonging to any of its member classes.
+#
+# Member classes are stored in a {SortedSet} sorted alphabetically by name.
+# Redundant subclasses are dropped automatically: if a superclass is already
+# present, its subclasses add no information and are removed.
+#
+# @example Basic usage
+#   union = String | Integer   # => UnionType(Integer | String)
+#   union === "hello"          # => true
+#   union === 42               # => true
+#   union === :sym             # => false
+#
+# @example case/when
+#   case value
+#   when String | Integer then "string or int"
+#   when Float            then "float"
+#   end
+#
+# @example Superclass deduplication
+#   UnionType[Integer, Float, Numeric]  # => UnionType(Numeric)
 class UnionType
   include Enumerable
 
+  # @private
   class Entry
     include Comparable
 
@@ -13,33 +34,81 @@ class UnionType
   end
   private_constant :Entry
 
+  # Creates a frozen {UnionType} from the given classes.
+  # Equivalent to {.new} but reads more naturally as a literal.
+  #
+  # @param classes [Array<Class>] one or more classes
+  # @return [UnionType]
+  #
+  # @example
+  #   UnionType[String, Integer]  # => UnionType(Integer | String)
   def self.[](*classes) = new(*classes)
 
+  # @param classes [Array<Class>] one or more classes to include in the union.
+  #   Subclasses of other members are dropped automatically.
+  # @raise [ArgumentError] if no classes are given
   def initialize(*classes)
     raise ArgumentError, "requires at least one class" if classes.empty?
 
     minimal = classes.reject { |c| classes.any? { |other| c != other && c < other } }
-    @types = SortedSet.new(minimal.map { Entry.new(_1) })
+    @types = SortedSet.new(minimal.map { Entry.new(_1) }).freeze
+    freeze
   end
 
+  # Yields each member class in sorted (alphabetical) order.
+  # Required by {Enumerable}; enables {#to_a}, {#map}, {#include?}, etc.
+  #
+  # @yieldparam klass [Class]
+  # @return [self]
   def each(&block)
     @types.each { block.call(_1.klass) }
   end
 
-  # Supports case/when and the === operator.
+  # Returns +true+ if +value+ is an instance of any member class.
+  # This makes {UnionType} work in +case+/+when+ expressions.
+  #
+  # @param value [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #   (String | Integer) === "hi"  # => true
+  #   (String | Integer) === :sym  # => false
   def ===(value)
     any? { _1 === value }
   end
 
-  # The underlying SortedSet of Entry objects (sorted by class name).
+  # The underlying {SortedSet} of internal entry objects.
+  # Entries are sorted by class name; use {#to_a} to get plain {Class} objects.
+  #
+  # @return [SortedSet]
   def types
     @types
   end
 
+  # Returns +true+ if this union covers +klass+ — i.e. +klass+ is a member or
+  # a subclass of a member.
+  #
+  # @param klass [Class]
+  # @return [Boolean]
+  #
+  # @example
+  #   (Numeric | String).cover?(Integer)  # => true  (Integer < Numeric)
+  #   (Numeric | String).cover?(Numeric)  # => true  (exact member)
+  #   (Integer | String).cover?(Numeric)  # => false (superclass, not covered)
   def cover?(klass)
     any? { klass <= _1 }
   end
 
+  # Returns a new {UnionType} that is the union of +self+ and +other+.
+  # Redundant subclasses are removed as in {.new}.
+  #
+  # @param other [Class, UnionType]
+  # @return [UnionType]
+  # @raise [TypeError] if +other+ is not a {Class} or {UnionType}
+  #
+  # @example
+  #   (String | Integer) | Float   # => UnionType(Float | Integer | String)
+  #   [String, Integer, Float].reduce(:|)  # => UnionType(Float | Integer | String)
   def |(other)
     case other
     when Class      then UnionType.new(*self, other)
@@ -48,8 +117,18 @@ class UnionType
     end
   end
 
-  # Returns a new UnionType covering only values matched by both unions,
-  # or nil when the intersection is empty.
+  # Returns a new {UnionType} containing only classes matched by *both* unions,
+  # keeping the more specific class when one is a subclass of the other.
+  # Returns +nil+ when the intersection is empty.
+  #
+  # @param other [Class, UnionType]
+  # @return [UnionType, nil]
+  # @raise [TypeError] if +other+ is not a {Class} or {UnionType}
+  #
+  # @example
+  #   (String | Integer) & (Integer | Float)  # => UnionType(Integer)
+  #   (String | Integer) & Numeric            # => UnionType(Integer)
+  #   (String | Integer) & Float              # => nil
   def &(other)
     other_types = case other
                   when UnionType then other.to_a
@@ -68,15 +147,22 @@ class UnionType
     UnionType.new(*classes) unless classes.empty?
   end
 
+  # Value equality: two unions are equal when they contain the same classes.
+  # Argument order does not matter.
+  #
+  # @param other [Object]
+  # @return [Boolean]
   def ==(other)
     other.class == UnionType && to_a == other.to_a
   end
   alias eql? ==
 
+  # @return [Integer] hash consistent with {#eql?}, for use as a Hash key
   def hash
     to_a.hash
   end
 
+  # @return [String] human-readable representation, e.g. +UnionType(Integer | String)+
   def inspect
     "UnionType(#{map(&:name).join(" | ")})"
   end

data/lib/union_type/version.rb

@@ -1,3 +1,5 @@
 class UnionType
-  VERSION = "0.1.0"
+  # The current gem version.
+  # @return [String]
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: union-type
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Bogdan Gusiev
@@ -58,13 +58,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/union-type-no-ext.rb
 - lib/union-type.rb
 - lib/union_type/core_ext.rb
 - lib/union_type/union_type.rb
 - lib/union_type/version.rb
-homepage: https://github.com/bogdangusiev/union-type
+homepage: https://github.com/bogdan/ruby-union-type
 licenses:
 - MIT
 metadata: {}