domainic-type 0.1.0.alpha.3.3.0 → 0.1.0.alpha.3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5342f3d3bb47776a4cb27404a0a244d8e0d2761f14de0fc1efe0638ac354c387
-  data.tar.gz: e5c55975ec267fba4623239df150111b6bb13eda48448ff4e026007e50342578
+  metadata.gz: e864e12054b6928f12f7465eace3657aaa736e264a1655e7838ec4f2e658ebed
+  data.tar.gz: ac7c71c1bd2c2f992bb6aca1306291838a4b7eabc77326130db553de8a9dc18f
 SHA512:
-  metadata.gz: c1563338aa961165140ef8d72d22c04d9f46e5c08fd95c02b037d32b74f21570b136c7b07094093b4dd47c59b5be6b7cfaa003114ced0e4aad963a15305088e5
-  data.tar.gz: 01751a3ccf57ddea40d185aa6d04e12ea7a78bd94c0770aeb4af8dbd449d43ac0eec5eda64f91fe1828ff05ab0e2a53d8b24b78f4c13347c9fbaeae343be928b
+  metadata.gz: 6029d7d12cb562dd7f2688472f0da97bcb548c544f163cf5215736d82ee0927e6f2c4ff87cc0d1818eefe722d10ac0ee2dd4ebccabff45412793340928e63cb8
+  data.tar.gz: 7ba6d7e41e431f2dd401bffecd60701a9dfeab35eeea3bef9085e97941d1b8327ddfd7cbe5febc577a0e1b3cce49147f6b686b56f1f6251257836d58327d198d

data/.yardopts

@@ -0,0 +1,11 @@
+--title Domainic::Type
+--readme README.md
+--no-private
+--protected
+--markup markdown
+--markup-provider redcarpet
+--embed-mixins
+--tag rbs
+--hide-tag rbs
+--files CHANGELOG.md,LICENSE,docs/USAGE.md
+'lib/**/*.rb'

data/docs/USAGE.md

@@ -9,6 +9,7 @@ introduction and installation instructions.
 * [Core Concepts](#core-concepts)
   * [Basic Type Validation](#basic-type-validation)
   * [Type Constraints](#type-constraints)
+  * [Custom Constraints](#custom-constraints)
   * [Error Messages](#error-messages)
 * [Built-in Types](#built-in-types)
   * [Simple Types](#simple-types)
@@ -131,6 +132,51 @@ numbers = _Array
   .containing(42)           # Must include 42
 ```
 
+### Custom Constraints
+
+All types in Domainic::Type support adding custom constraints through the `satisfies` method. This is useful when you
+need validation logic that goes beyond what the built-in constraints provide:
+
+```ruby
+# Basic value range validation that can't be expressed with built-in constraints
+kelvin = _Float.satisfies(
+  ->(value) { value >= 0.0 },
+  description: 'being a valid Kelvin temperature',
+  violation_description: 'temperature below absolute zero'
+)
+
+kelvin.validate!(0.0)    # => true
+kelvin.validate!(-1.0)
+# => TypeError: Expected Float(being a valid Kelvin temperature), got Float(temperature below absolute zero)
+
+# Validating relationships between values in complex objects
+booking = _Hash
+  .of(_Symbol => _DateTime)
+  .containing_keys(:check_in, :check_out)
+  .satisfies(
+    ->(dates) { dates[:check_out] > dates[:check_in] },
+    description: 'having valid stay duration',
+    violation_description: 'check-out not after check-in'
+  )
+
+# Access different parts of objects with accessors
+balanced_ledger = _Array
+  .of(_Hash)
+  .satisfies(
+    ->(entries) { entries.sum { |e| e[:amount] }.zero? },
+    accessor: :entries,
+    description: 'having balanced transactions',
+    violation_description: 'transactions do not sum to zero'
+  )
+```
+
+The `satisfies` method accepts:
+
+* A predicate function that returns true/false for validating values
+* Optional description that explains what makes a value valid
+* Optional violation_description that explains why validation failed
+* Optional accessor to validate specific parts of complex objects
+
 ### Error Messages
 
 Error messages clearly indicate what validation failed and why. For compound constraints, the error message shows all
@@ -410,14 +456,23 @@ Available in nilable variant `_DateTime?`.
 
 #### _DateTimeString
 
-String-based datetime validation with format constraints:
+String-based datetime validation with format constraints and full datetime behavior support:
 
 ```ruby
 _DateTimeString                 # Basic datetime string validation
+  # Format constraints
   .having_american_format      # MM/DD/YYYY format
   .having_european_format     # DD.MM.YYYY format
   .having_iso8601_format     # ISO 8601 format
   .having_rfc2822_format    # RFC 2822 format
+
+  # Inherits all datetime constraints
+  .being_after('2024-01-01')     # Must be after date
+  .being_before('2024-12-31')    # Must be before date
+  .being_between(               # Must be in range
+    '2024-01-01',
+    '2024-12-31'
+  )
 ```
 
 Also available as `_DateString` and in nilable variants `_DateTimeString?`, `_DateString?`.

data/lib/domainic/type/behavior/date_time_behavior.rb

@@ -103,10 +103,14 @@ module Domainic
             Time.at(value).to_datetime
           when String
             DATETIME_PATTERNS.each do |pattern|
-              return DateTime.strptime(value, pattern)
+              result = DateTime.strptime(value, pattern)
+              # Validate the parsing preserved the original values by reformatting
+              # the result with the same pattern and comparing
+              return result if value == result.strftime(pattern)
             rescue ArgumentError
               next
             end
+            DateTime.parse(value) # Fallback to Ruby's built-in parser and allow it to raise.
           else
             DateTime.parse(value) # Fallback to Ruby's built-in parser and allow it to raise.
           end

data/lib/domainic/type/behavior.rb

@@ -186,6 +186,22 @@ module Domainic
         end
       end
 
+      # Add a custom constraint to this type.
+      #
+      # @param proc [Proc] the constraint to add
+      # @param accessor [Type::Accessor] the accessor to constrain
+      # @param options [Hash{Symbol => Object}] additional constraint options
+      #
+      # @return [self] for chaining constraints
+      # @rbs (
+      #   Proc proc,
+      #   ?accessor: Type::accessor,
+      #   **untyped options
+      #   ) -> Behavior
+      def satisfies(proc, accessor: :self, **options)
+        constrain accessor, :predicate, proc, **options
+      end
+
       # Convert the type to a String representation.
       #
       # @return [String] The type as a String

data/lib/domainic/type/config/registry.yml

@@ -62,6 +62,9 @@ constraints:
   polarity:
     constant: Domainic::Type::Constraint::PolarityConstraint
     require_path: domainic/type/constraint/constraints/polarity_constraint
+  predicate:
+    constant: Domainic::Type::Constraint::PredicateConstraint
+    require_path: domainic/type/constraint/constraints/predicate_constraint
   range:
     constant: Domainic::Type::Constraint::RangeConstraint
     require_path: domainic/type/constraint/constraints/range_constraint

data/lib/domainic/type/constraint/constraints/nor_constraint.rb

@@ -39,7 +39,7 @@ module Domainic
         # @rbs override
         def short_description
           descriptions = @expected.map(&:short_description)
-          return descriptions.first if descriptions.size == 1
+          return "not #{descriptions.first}" if descriptions.size == 1
 
           *first, last = descriptions
           "#{first.join(', ')} nor #{last}"

data/lib/domainic/type/constraint/constraints/predicate_constraint.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating values using a custom predicate function.
+      #
+      # This constraint allows for custom validation logic through a Proc that returns
+      # a boolean value. It enables users to create arbitrary validation rules when
+      # the built-in constraints don't cover their specific needs.
+      #
+      # @example Basic usage
+      #   constraint = PredicateConstraint.new(:self, ->(x) { x > 0 })
+      #   constraint.satisfied?(1)   # => true
+      #   constraint.satisfied?(-1)  # => false
+      #
+      # @example With custom violation description
+      #   constraint = PredicateConstraint.new(:self, ->(x) { x > 0 }, violation_description: 'not greater than zero')
+      #   constraint.satisfied?(-1)  # => false
+      #   constraint.short_violation_description  # => "not greater than zero"
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class PredicateConstraint
+        # @rbs!
+        #   type expected = ^(untyped value) -> bool
+        #
+        #   type options = { ?violation_description: String}
+
+        include Behavior #[expected, untyped, options]
+
+        # Get a description of what the constraint expects.
+        #
+        # @note This constraint type does not provide a description as predicates are arbitrary.
+        #
+        # @return [String] an empty string
+        # @rbs override
+        def short_description = ''
+
+        # Get a description of why the predicate validation failed.
+        #
+        # @return [String] the custom violation description if provided
+        # @rbs override
+        def short_violation_description
+          # @type ivar @options: { ?violation_description: String }
+          @options.fetch(:violation_description, '')
+        end
+
+        protected
+
+        # Check if the value satisfies the predicate function.
+        #
+        # @return [Boolean] true if the predicate returns true
+        # @rbs override
+        def satisfies_constraint?
+          @expected.call(@actual)
+        end
+
+        # Validate that the expectation is a Proc.
+        #
+        # @param expectation [Object] the expectation to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a Proc
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if expectation.is_a?(Proc)
+
+          raise ArgumentError, 'Expectation must be a Proc'
+        end
+      end
+    end
+  end
+end

data/sig/domainic/type/behavior.rbs

@@ -125,6 +125,15 @@ module Domainic
       # @return [void]
       def initialize: (**untyped) -> void
 
+      # Add a custom constraint to this type.
+      #
+      # @param proc [Proc] the constraint to add
+      # @param accessor [Type::Accessor] the accessor to constrain
+      # @param options [Hash{Symbol => Object}] additional constraint options
+      #
+      # @return [self] for chaining constraints
+      def satisfies: (Proc proc, ?accessor: Type::accessor, **untyped options) -> Behavior
+
       # Convert the type to a String representation.
       #
       # @return [String] The type as a String

data/sig/domainic/type/constraint/constraints/predicate_constraint.rbs

@@ -0,0 +1,56 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating values using a custom predicate function.
+      #
+      # This constraint allows for custom validation logic through a Proc that returns
+      # a boolean value. It enables users to create arbitrary validation rules when
+      # the built-in constraints don't cover their specific needs.
+      #
+      # @example Basic usage
+      #   constraint = PredicateConstraint.new(:self, ->(x) { x > 0 })
+      #   constraint.satisfied?(1)   # => true
+      #   constraint.satisfied?(-1)  # => false
+      #
+      # @example With custom violation description
+      #   constraint = PredicateConstraint.new(:self, ->(x) { x > 0 }, violation_description: 'not greater than zero')
+      #   constraint.satisfied?(-1)  # => false
+      #   constraint.short_violation_description  # => "not greater than zero"
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class PredicateConstraint
+        type expected = ^(untyped value) -> bool
+
+        type options = { ?violation_description: String }
+
+        include Behavior[expected, untyped, options]
+
+        # Get a description of what the constraint expects.
+        #
+        # @note This constraint type does not provide a description as predicates are arbitrary.
+        #
+        # @return [String] an empty string
+        def short_description: ...
+
+        # Get a description of why the predicate validation failed.
+        #
+        # @return [String] the custom violation description if provided
+        def short_violation_description: ...
+
+        # Check if the value satisfies the predicate function.
+        #
+        # @return [Boolean] true if the predicate returns true
+        def satisfies_constraint?: ...
+
+        # Validate that the expectation is a Proc.
+        #
+        # @param expectation [Object] the expectation to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a Proc
+        # @return [void]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: domainic-type
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.3.3.0
+  version: 0.1.0.alpha.3.4.0
 platform: ruby
 authors:
 - Aaron Allen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-27 00:00:00.000000000 Z
+date: 2024-12-30 00:00:00.000000000 Z
 dependencies: []
 description: Stop wrestling with complex type validations and unclear error messages.
   Domainic::Type brings type validation to Ruby that is both powerful and delightful
@@ -21,6 +21,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
 - README.md
@@ -59,6 +60,7 @@ files:
 - lib/domainic/type/constraint/constraints/ordering_constraint.rb
 - lib/domainic/type/constraint/constraints/parity_constraint.rb
 - lib/domainic/type/constraint/constraints/polarity_constraint.rb
+- lib/domainic/type/constraint/constraints/predicate_constraint.rb
 - lib/domainic/type/constraint/constraints/range_constraint.rb
 - lib/domainic/type/constraint/constraints/type_constraint.rb
 - lib/domainic/type/constraint/constraints/uniqueness_constraint.rb
@@ -125,6 +127,7 @@ files:
 - sig/domainic/type/constraint/constraints/ordering_constraint.rbs
 - sig/domainic/type/constraint/constraints/parity_constraint.rbs
 - sig/domainic/type/constraint/constraints/polarity_constraint.rbs
+- sig/domainic/type/constraint/constraints/predicate_constraint.rbs
 - sig/domainic/type/constraint/constraints/range_constraint.rbs
 - sig/domainic/type/constraint/constraints/type_constraint.rbs
 - sig/domainic/type/constraint/constraints/uniqueness_constraint.rbs
@@ -159,15 +162,16 @@ files:
 - sig/domainic/type/types/specification/union_type.rbs
 - sig/domainic/type/types/specification/void_type.rbs
 - sig/manifest.yaml
-homepage: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.3.0/domainic-type
+homepage: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.4.0/domainic-type
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/domainic/domainic/issues
-  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-type-v0.1.0-alpha.3.3.0
-  homepage_uri: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.3.0/domainic-type
+  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-type-v0.1.0-alpha.3.4.0
+  documentation_uri: https://rubydoc.info/gems/domainic-type/0.1.0.alpha.3.4.0
+  homepage_uri: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.4.0/domainic-type
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.3.0/domainic-type
+  source_code_uri: https://github.com/domainic/domainic/tree/domainic-type-v0.1.0-alpha.3.4.0/domainic-type
 post_install_message:
 rdoc_options: []
 require_paths: