domainic-type 0.1.0.alpha.2.1.0 → 0.1.0.alpha.3.0.0

data/lib/domainic/type/definitions.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Type
+    # A module providing convenient factory methods for creating type instances.
+    #
+    # This module serves as a temporary access point for type creation in the Domainic::Type
+    # system, offering a collection of factory methods with consistent naming patterns.
+    # Each method creates and configures a specific type instance, with optional nilable
+    # variants and aliases for common use cases.
+    #
+    # @note This module is considered temporary and may be significantly altered or removed
+    #   before the final release. It should not be considered part of the stable API.
+    #
+    # @example Basic type creation
+    #   include Domainic::Type::Definitions
+    #
+    #   string_type = _String()
+    #   array_type = _Array()
+    #   hash_type = _Hash()
+    #
+    # @example Creating nilable types
+    #   nullable_string = _String?()
+    #   nullable_array = _Array?()
+    #
+    # @example Using union types
+    #   string_or_symbol = _Union(String, Symbol)
+    #   boolean = _Boolean()  # Union of TrueClass and FalseClass
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    module Definitions
+      # rubocop:disable Naming/MethodName
+
+      # Creates an AnythingType instance.
+      #
+      # @example
+      #   type = _Anything
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::AnythingType] the created type
+      # @rbs (**__todo__ options) -> AnythingType
+      def _Anything(**options)
+        require 'domainic/type/types/specification/anything_type'
+        Domainic::Type::AnythingType.new(**options)
+      end
+      alias _Any _Anything
+
+      # Creates an ArrayType instance.
+      #
+      # @example
+      #   type = _Array
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::ArrayType] the created type
+      # @rbs (**__todo__ options) -> ArrayType
+      def _Array(**options)
+        require 'domainic/type/types/core/array_type'
+        Domainic::Type::ArrayType.new(**options)
+      end
+      alias _List _Array
+
+      # Creates a nilable ArrayType instance.
+      #
+      # @example
+      #   type = _Array?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Array or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _Array?(**options)
+        array = _Array(**options)
+        _Nilable(array)
+      end
+      alias _List? _Array?
+
+      # Creates a Boolean type.
+      #
+      # Represents a union of TrueClass and FalseClass.
+      #
+      # @example
+      #   type = _Boolean
+      #
+      # @return [Domainic::Type::UnionType] the created type
+      # @rbs () -> UnionType
+      def _Boolean
+        _Union(TrueClass, FalseClass).freeze
+      end
+      alias _Bool _Boolean
+
+      # Creates a nilable Boolean type.
+      #
+      # @example
+      #   type = _Boolean?
+      #
+      # @return [Domainic::Type::UnionType] the created type (TrueClass, FalseClass, or NilClass)
+      # @rbs () -> UnionType
+      def _Boolean?
+        _Nilable(_Boolean)
+      end
+      alias _Bool? _Boolean?
+
+      # Creates a DuckType instance.
+      #
+      # DuckType allows specifying behavior based on method availability.
+      #
+      # @example
+      #   type = _Duck(respond_to: :to_s)
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::DuckType] the created type
+      # @rbs (**__todo__ options) -> DuckType
+      def _Duck(**options)
+        require 'domainic/type/types/specification/duck_type'
+        Domainic::Type::DuckType.new(**options)
+      end
+      alias _Interface _Duck
+      alias _Protocol _Duck
+      alias _RespondingTo _Duck
+
+      # Creates an EnumType instance.
+      #
+      # EnumType restricts values to a specific set of literals.
+      #
+      # @example
+      #   type = _Enum(:red, :green, :blue)
+      #
+      # @param literals [Array<Object>] the allowed literals
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::EnumType] the created type
+      # @rbs (*untyped literals, **__todo__ options) -> EnumType
+      def _Enum(*literals, **options)
+        require 'domainic/type/types/specification/enum_type'
+        Domainic::Type::EnumType.new(*literals, **options)
+      end
+      alias _Literal _Enum
+
+      # Creates a nilable EnumType instance.
+      #
+      # @example
+      #   type = _Enum?(:red, :green, :blue)
+      #
+      # @param literals [Array<Object>] the allowed literals
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Enum or NilClass)
+      # @rbs (*untyped literals, **__todo__ options) -> UnionType
+      def _Enum?(*literals, **options)
+        enum = _Enum(*literals, **options)
+        _Nilable(enum)
+      end
+      alias _Literal? _Enum?
+
+      # Creates a FloatType instance.
+      #
+      # @example
+      #   type = _Float
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::FloatType] the created type
+      # @rbs (**__todo__ options) -> FloatType
+      def _Float(**options)
+        require 'domainic/type/types/core/float_type'
+        Domainic::Type::FloatType.new(**options)
+      end
+      alias _Decimal _Float
+      alias _Real _Float
+
+      # Creates a nilable FloatType instance.
+      #
+      # @example
+      #   type = _Float?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Float or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _Float?(**options)
+        float = _Float(**options)
+        _Nilable(float)
+      end
+      alias _Decimal? _Float?
+      alias _Real? _Float?
+
+      # Creates a HashType instance.
+      #
+      # @example
+      #   type = _Hash
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::HashType] the created type
+      # @rbs (**__todo__ options) -> HashType
+      def _Hash(**options)
+        require 'domainic/type/types/core/hash_type'
+        Domainic::Type::HashType.new(**options)
+      end
+      alias _Map _Hash
+
+      # Creates a nilable HashType instance.
+      #
+      # @example
+      #   type = _Hash?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Hash or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _Hash?(**options)
+        hash = _Hash(**options)
+        _Nilable(hash)
+      end
+      alias _Map? _Hash?
+
+      # Creates an IntegerType instance.
+      #
+      # @example
+      #   type = _Integer
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::IntegerType] the created type
+      # @rbs (**__todo__ options) -> IntegerType
+      def _Integer(**options)
+        require 'domainic/type/types/core/integer_type'
+        Domainic::Type::IntegerType.new(**options)
+      end
+      alias _Int _Integer
+      alias _Number _Integer
+
+      # Creates a nilable IntegerType instance.
+      #
+      # @example
+      #   type = _Integer?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Integer or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _Integer?(**options)
+        integer = _Integer(**options)
+        _Nilable(integer)
+      end
+      alias _Int? _Integer?
+      alias _Number? _Integer?
+
+      # Creates a Nilable (nullable) type.
+      #
+      # Combines one or more types with `NilClass` to allow nil values.
+      #
+      # @example
+      #   type = _Nilable(String, Symbol)
+      #
+      # @param types [Array<Class, Module, Behavior>] the base types
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (NilClass or other specified types)
+      # @rbs (*Class | Module | Behavior[untyped, untyped, untyped] types, **__todo__ options) -> UnionType
+      def _Nilable(*types, **options)
+        _Union(NilClass, *types, **options)
+      end
+      alias _Nullable _Nilable
+
+      # Creates a StringType instance.
+      #
+      # @example
+      #   type = _String
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::StringType] the created type
+      # @rbs (**__todo__ options) -> StringType
+      def _String(**options)
+        require 'domainic/type/types/core/string_type'
+        Domainic::Type::StringType.new(**options)
+      end
+      alias _Text _String
+
+      # Creates a nilable StringType instance.
+      #
+      # @example
+      #   type = _String?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (String or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _String?(**options)
+        string = _String(**options)
+        _Nilable(string)
+      end
+      alias _Text? _String?
+
+      # Creates a SymbolType instance.
+      #
+      # @example
+      #   type = _Symbol
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::SymbolType] the created type
+      # @rbs (**__todo__ options) -> SymbolType
+      def _Symbol(**options)
+        require 'domainic/type/types/core/symbol_type'
+        Domainic::Type::SymbolType.new(**options)
+      end
+      alias _Interned _Symbol
+
+      # Creates a nilable SymbolType instance.
+      #
+      # @example
+      #   type = _Symbol?
+      #
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type (Symbol or NilClass)
+      # @rbs (**__todo__ options) -> UnionType
+      def _Symbol?(**options)
+        symbol = _Symbol(**options)
+        _Nilable(symbol)
+      end
+      alias _Interned? _Symbol?
+
+      # Creates a UnionType instance.
+      #
+      # Allows combining multiple types into a single union type.
+      #
+      # @example
+      #   type = _Union(String, Symbol)
+      #
+      # @param types [Array<Class, Module, Behavior>] the types included in the union
+      # @param options [Hash] additional configuration options
+      #
+      # @return [Domainic::Type::UnionType] the created type
+      # @rbs (*Class | Module | Behavior[untyped, untyped, untyped] types, **__todo__ options) -> UnionType
+      def _Union(*types, **options)
+        require 'domainic/type/types/specification/union_type'
+        Domainic::Type::UnionType.new(*types, **options)
+      end
+      alias _Either _Union
+
+      # Creates a VoidType instance.
+      #
+      # Represents an operation that returns no value.
+      #
+      # @example
+      #   type = _Void
+      #
+      # @return [Domainic::Type::VoidType] the created type
+      # @rbs () -> VoidType
+      def _Void
+        require 'domainic/type/types/specification/void_type'
+        Domainic::Type::VoidType.new
+      end
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end

data/lib/domainic/type/types/core/array_type.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/enumerable_behavior'
+
+module Domainic
+  module Type
+    # A type for validating Array objects with flexible element and size constraints
+    #
+    # This class provides a comprehensive set of validations specifically designed for Array
+    # objects, including element type checking, value inclusion/exclusion, ordering, and all
+    # standard enumerable validations.
+    #
+    # Key features:
+    # - Element type validation
+    # - Element presence/absence validation
+    # - Uniqueness constraints
+    # - Order constraints
+    # - Size constraints (via EnumerableBehavior)
+    # - Standard collection validations (via EnumerableBehavior)
+    #
+    # @example Basic usage
+    #   type = ArrayType.new
+    #   type.of(String)                # enforce element type
+    #   type.containing(1, 2)          # require specific elements
+    #   type.having_size(3)            # exact size constraint
+    #   type.being_distinct            # unique elements
+    #
+    # @example Complex constraints
+    #   type = ArrayType.new
+    #   type
+    #     .of(Integer)                 # type constraints
+    #     .being_ordered               # must be sorted
+    #     .having_size_between(2, 5)   # size range
+    #     .starting_with(1)            # first element
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class ArrayType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::EnumerableBehavior
+
+      intrinsic :self, :type, Array, abort_on_failure: true, description: :not_described
+    end
+  end
+end

data/lib/domainic/type/types/core/float_type.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/numeric_behavior'
+
+module Domainic
+  module Type
+    # A type for validating Float objects with extensive numeric validation capabilities.
+    #
+    # This class provides a comprehensive set of validations specifically designed for
+    # floating-point values, including basic type checking and all numeric validations
+    # like finiteness, polarity, and range constraints. It properly handles floating-point
+    # arithmetic by using appropriate tolerances in comparisons.
+    #
+    # @example Basic usage
+    #   type = FloatType.new
+    #   type.validate(3.14)   # => true
+    #   type.validate(42)     # => false
+    #   type.validate("3.14") # => false
+    #
+    # @example With numeric constraints
+    #   type = FloatType.new
+    #   type
+    #     .being_positive
+    #     .being_finite
+    #     .being_less_than(10.0)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class FloatType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::NumericBehavior
+
+      intrinsic :self, :type, Float, abort_on_failure: true, description: :not_described
+    end
+  end
+end

data/lib/domainic/type/types/core/hash_type.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/enumerable_behavior'
+
+module Domainic
+  module Type
+    # A type for validating Hash objects with flexible key and value constraints
+    #
+    # This class provides a comprehensive set of validations specifically designed
+    # for Hash objects, including key/value type checking, inclusion/exclusion of
+    # specific keys or values, and all standard enumerable validations.
+    #
+    # Key features:
+    # - Key type validation
+    # - Value type validation
+    # - Key presence/absence checking
+    # - Value presence/absence checking
+    # - Size constraints (via EnumerableBehavior)
+    # - Standard collection validations (via EnumerableBehavior)
+    #
+    # @example Basic usage
+    #   type = HashType.new
+    #   type.of(String => Integer)          # enforce key/value types
+    #   type.containing_keys('a', 'b')      # require specific keys
+    #   type.containing_values(1, 2)        # require specific values
+    #   type.having_size(2)                 # exact size constraint
+    #
+    # @example Complex constraints
+    #   type = HashType.new
+    #   type
+    #     .of(Symbol => String)             # type constraints
+    #     .containing_keys(:name, :email)   # required keys
+    #     .excluding_values(nil, '')        # no empty values
+    #     .having_size_between(2, 5)        # size range
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class HashType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::EnumerableBehavior
+
+      intrinsic :self, :type, Hash, abort_on_failure: true, description: :not_described
+
+      # Validate that the hash contains specific keys
+      #
+      # @example
+      #   type.containing_keys(:name, :email)
+      #   type.validate({ name: 'John', email: 'john@example.com' })  # => true
+      #   type.validate({ name: 'John' })                            # => false
+      #
+      # @param keys [Array<Object>] the keys that must be present
+      # @return [self] self for method chaining
+      # @rbs (*untyped keys) -> self
+      def containing_keys(*keys)
+        including = keys.map do |key|
+          @constraints.prepare :entries, :inclusion, key
+        end
+        constrain :keys, :and, including, concerning: :key_inclusion, description: 'keys'
+      end
+      alias including_keys containing_keys
+
+      # Validate that the hash contains specific values
+      #
+      # @example
+      #   type.containing_values('active', 'pending')
+      #   type.validate({ status: 'active' })   # => true
+      #   type.validate({ status: 'inactive' }) # => false
+      #
+      # @param values [Array<Object>] the values that must be present
+      # @return [self] self for method chaining
+      # @rbs (*untyped values) -> self
+      def containing_values(*values)
+        including = values.map do |value|
+          @constraints.prepare :entries, :inclusion, value
+        end
+        constrain :values, :and, including, concerning: :values_inclusion, description: 'values'
+      end
+      alias including_values containing_values
+
+      # Validate that the hash does not contain specific keys
+      #
+      # @example
+      #   type.excluding_keys(:admin, :superuser)
+      #   type.validate({ user: 'John' })           # => true
+      #   type.validate({ admin: true })            # => false
+      #
+      # @param keys [Array<Object>] the keys that must not be present
+      # @return [self] self for method chaining
+      # @rbs (*untyped keys) -> self
+      def excluding_keys(*keys)
+        including = keys.map do |key|
+          @constraints.prepare :entries, :inclusion, key
+        end
+        constrain :keys, :nor, including, concerning: :key_exclusion, description: 'keys'
+      end
+      alias omitting_keys excluding_keys
+
+      # Validate that the hash does not contain specific values
+      #
+      # @example
+      #   type.excluding_values(nil, '')
+      #   type.validate({ name: 'John' })   # => true
+      #   type.validate({ name: nil })      # => false
+      #
+      # @param values [Array<Object>] the values that must not be present
+      # @return [self] self for method chaining
+      # @rbs (*untyped values) -> self
+      def excluding_values(*values)
+        including = values.map do |value|
+          @constraints.prepare :entries, :inclusion, value
+        end
+        constrain :values, :nor, including, concerning: :values_exclusion, description: 'values'
+      end
+      alias omitting_values excluding_values
+
+      # Validate the hash to have the given key type and value type.
+      #
+      # @example
+      #   type.of(String => Integer)
+      #   type.validate({ 'a' => 1 })   # => true
+      #   type.validate({ 1 => 'a' })   # => false
+      #
+      # @param key_to_value_type [Hash{Object => Object}] the key type and value type that the hash must have
+      #
+      # @raise [ArgumentError] if the key_to_value_type pair is not a Hash or does not have exactly one entry
+      # @return [self] self for method chaining
+      # @rbs (Hash[untyped, untyped] key_to_value_type) -> self
+      def of(key_to_value_type)
+        raise ArgumentError, 'The key_to_value_type pair must be a Hash' unless key_to_value_type.is_a?(Hash)
+        raise ArgumentError, 'The key_to_value_type pair must have exactly one entry' unless key_to_value_type.size == 1
+
+        key_type = @constraints.prepare :self, :type, key_to_value_type.keys.first
+        value_type = @constraints.prepare :self, :type, key_to_value_type.values.first
+
+        constrain :keys, :all, key_type, concerning: :key_type, description: 'having keys of'
+        constrain :values, :all, value_type, concerning: :value_type, description: 'having values of'
+      end
+    end
+  end
+end

data/lib/domainic/type/types/core/integer_type.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/numeric_behavior'
+
+module Domainic
+  module Type
+    # A type for validating Integer objects with extensive numeric validation capabilities.
+    #
+    # This class provides a comprehensive set of validations specifically designed for
+    # integer values, including basic type checking and all numeric validations like
+    # divisibility, parity, polarity, and range constraints.
+    #
+    # @example Basic usage
+    #   type = IntegerType.new
+    #   type.validate(42)     # => true
+    #   type.validate(3.14)   # => false
+    #   type.validate("42")   # => false
+    #
+    # @example With numeric constraints
+    #   type = IntegerType.new
+    #   type
+    #     .being_positive
+    #     .being_even
+    #     .being_less_than(100)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class IntegerType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::NumericBehavior
+
+      intrinsic :self, :type, Integer, abort_on_failure: true, description: :not_described
+    end
+  end
+end

data/lib/domainic/type/types/core/string_type.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/string_behavior'
+
+module Domainic
+  module Type
+    # A type for validating String objects with comprehensive string-specific constraints
+    #
+    # This type provides a complete set of string validation capabilities including case
+    # formatting, character set validation, pattern matching, and size constraints. It
+    # combines core string type checking with rich string-specific behaviors.
+    #
+    # Key features:
+    # - Basic string type validation
+    # - Case checking (upper, lower, mixed, title)
+    # - Character set validation (ASCII, alphanumeric, etc.)
+    # - Pattern matching with regular expressions
+    # - Size/length constraints
+    # - String content validation
+    #
+    # @example Basic usage
+    #   type = StringType.new
+    #   type.validate("hello")   # => true
+    #   type.validate(123)       # => false
+    #
+    # @example Complex string validation
+    #   type = StringType.new
+    #     .being_ascii
+    #     .being_alphanumeric
+    #     .having_size_between(3, 20)
+    #     .not_matching(/[^a-z0-9]/)
+    #
+    # @example Case validation
+    #   type = StringType.new
+    #     .being_titlecase
+    #     .matching(/^[A-Z]/)
+    #     .having_minimum_size(2)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class StringType
+      # @rbs! extend Behavior::ClassMethods
+
+      include Behavior
+      include Behavior::StringBehavior
+
+      intrinsic :self, :type, String, abort_on_failure: true, description: :not_described
+    end
+  end
+end