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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18b90d10d73335f1c1c10ab77a9cf2caff65fb40b898a8dc84cd782430373919
-  data.tar.gz: d943105b0d45b9042ff9352286ef4f716e3d38c516820476932acd4922473dd6
+  metadata.gz: 7e4f8e0bb4883a197a5ed2f87b53a6dbc60ae70a41f48f6369881e8a5a5249b0
+  data.tar.gz: b512246f56da3aa04d9b068c080324a7ab507f96b6749a6ed8701a8bc8615901
 SHA512:
-  metadata.gz: d776067c6a20cce90560648dd68354f0e4ce8daf737246f44cb304c32e6d19d4dff089808c8e142f6669e5a6ea2cf72abed66569d0bbc76140c8ebe95ebad9a5
-  data.tar.gz: ca50e98a6c550da3f57768567cd868bce69af7cf94e609f6ec8600b88a266f717aa468c61e502f763256d8f6a2bac637301175f8b1c386195c0e3ff9b1bc29ef
+  metadata.gz: 5d807fab460c97af3e8fc50acb0f834ae8bc881d56507c668908d1baaa3b983516280a79c361fe30da893e38aeffa04561f265605c9c33633c64578a4461550f
+  data.tar.gz: c243d9fc6559e8d3be625c7db153d9964d2e36bcda90a33ba2e75f0cb8e69269cfa53542dddabf8fa7a4671da676bde29db7ae4893c5659d1702f38ff5a8f50f

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Break Versioning].
+
+## [Unreleased]
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Break Versioning]: https://www.taoensso.com/break-versioning
+
+<!-- versions -->
+
+[Unreleased]: https://github.com/domainic/domainic/tree/main/domainic-type

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Aaron Allen
+Copyright (c) Aaron Allen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,31 @@
-# Domainic
+# Domainic::Type
 
-Tooling and utilities for domain-driven design in Ruby.
+[![Domainic::Type Version](https://img.shields.io/gem/v/domainic-type?style=for-the-badge&logo=rubygems&logoColor=white&logoSize=auto&label=Gem%20Version)](https://rubygems.org/gems/domainic-type)
+[![Domainic::Type License](https://img.shields.io/github/license/domainic/domainic?logo=opensourceinitiative&logoColor=white&logoSize=auto&style=for-the-badge)](./LICENSE)
+[![Domainic::Type Open Issues](https://img.shields.io/github/issues-search/domainic/domainic?label=open%20issues&logo=github&logoSize=auto&query=is%3Aopen%20label%3Adomainic-type&color=red&style=for-the-badge)](https://github.com/domainic/domainic/issues?q=state%3Aopen%20label%3Adomainic-type%20)
 
-## WARNING
+> [!IMPORTANT]  
+> We're running an experiment with Domainic::Type! Help us explore flexible type validation in Ruby by trying our
+> [alpha release](../docs/experiments/domainic-type-alpha-3/README.md). Your feedback is invaluable for shaping
+> the future of domain-driven design in Ruby.
 
-All gems in this package are in early development and are not yet ready for production use.
+A flexible type validation system for Ruby, offering composable, readable type constraints with elegant error messages.
+
+Stop wrestling with complex type validations and unclear error messages. Domainic::Type brings type validation to Ruby
+that is both powerful and delightful to use. Build composable type constraints with crystal-clear error messages that
+actually tell you what went wrong. From simple type checks to complex collection validations, make your types work for
+you, not against you!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'domainic-type', '~> 0.1.0.alpha.3'
+```
+
+Or install it yourself as:
+
+```bash
+gem install domainic-type --pre
+```

data/lib/domainic/type/accessors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Type
+    # @rbs!
+    #   type accessor = :abs | :begin | :chars | :class | :count | :end | :entries | :first | :keys | :last | :length |
+    #                   :self | :size | :values
+
+    # A list of valid access methods that can be used to retrieve values for constraint validation.
+    # These methods represent common Ruby interfaces for accessing collection sizes, ranges, and values.
+    #
+    # - :abs                       - For absolute values
+    # - :begin, :end               - For Range-like objects
+    # - :class                     - For type checking
+    # - :count, :length, :size     - For measuring collections
+    # - :entries, :chars           - For accessing sequence elements
+    # - :first, :last              - For accessing sequence endpoints
+    # - :keys, :values             - For Hash-like objects
+    # - :self                      - For operating directly on the value
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    # @return [Array<Symbol>]
+    ACCESSORS = %i[
+      class
+      self
+      entries
+      chars
+      abs
+      count
+      size
+      length
+      first
+      last
+      begin
+      end
+      keys
+      values
+    ].freeze #: Array[accessor]
+  end
+end

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

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/behavior/sizable_behavior'
+
+module Domainic
+  module Type
+    module Behavior
+      # A module providing enumerable-specific validation behaviors for types.
+      #
+      # This module extends the base Type::Behavior with methods specifically designed for validating enumerable
+      # collections. It provides a fluent interface for common enumerable validations such as uniqueness, emptiness,
+      # ordering, and size constraints.
+      #
+      # @example Basic usage
+      #   class ArrayType
+      #     include Domainic::Type::Behavior::EnumerableBehavior
+      #
+      #     def initialize
+      #       super
+      #       being_empty                  # validates array is empty
+      #       having_minimum_count(5)      # validates at least 5 elements
+      #       containing(1, 2, 3)          # validates specific elements
+      #     end
+      #   end
+      #
+      # @example Combining constraints
+      #   class OrderedArrayType
+      #     include Domainic::Type::Behavior::EnumerableBehavior
+      #
+      #     def initialize
+      #       super
+      #       being_ordered
+      #       being_populated
+      #       having_maximum_count(10)
+      #     end
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module EnumerableBehavior
+        include SizableBehavior
+
+        def being_distinct
+          # @type self: Object & Behavior
+          constrain :entries, :uniqueness, description: 'being'
+        end
+        alias being_unique being_distinct
+        alias distinct being_distinct
+        alias unique being_distinct
+
+        # Validate that the enumerable contains duplicate elements.
+        #
+        # Creates an inverse uniqueness constraint that ensures the collection has at least one duplicate element.
+        #
+        # @example
+        #   type.being_duplicative
+        #   type.validate([1, 1, 2])   # => true
+        #   type.validate([1, 2, 3])   # => false
+        #
+        # @return [self] self for method chaining
+        # @rbs ()-> Behavior
+        def being_duplicative
+          # @type self: Object & Behavior
+          unique = @constraints.prepare :self, :uniqueness
+          constrain :entries, :not, unique, concerning: :uniqueness, description: 'being'
+        end
+        alias being_redundant being_duplicative
+        alias being_repetitive being_duplicative
+        alias duplicative being_duplicative
+        alias redundant being_duplicative
+        alias repetitive being_duplicative
+
+        # Validate that the enumerable is empty.
+        #
+        # Creates a constraint that ensures the collection has no elements.
+        #
+        # @example
+        #   type.being_empty
+        #   type.validate([])     # => true
+        #   type.validate([1])    # => false
+        #
+        # @return [self] self for method chaining
+        # @rbs ()-> Behavior
+        def being_empty
+          # @type self: Object & Behavior
+          constrain :entries, :emptiness, description: 'being'
+        end
+        alias being_vacant being_empty
+        alias empty being_empty
+        alias vacant being_empty
+
+        # Validate that the enumerable contains elements.
+        #
+        # Creates an inverse emptiness constraint that ensures the collection has at least one element.
+        #
+        # @example
+        #   type.being_populated
+        #   type.validate([1])    # => true
+        #   type.validate([])     # => false
+        #
+        # @return [self] self for method chaining
+        # @rbs ()-> Behavior
+        def being_populated
+          # @type self: Object & Behavior
+          empty = @constraints.prepare :self, :emptiness
+          constrain :entries, :not, empty, concerning: :emptiness, description: 'being'
+        end
+        alias being_inhabited being_populated
+        alias being_occupied being_populated
+        alias populated being_populated
+        alias inhabited being_populated
+        alias occupied being_populated
+
+        # Validate that the enumerable elements are in sorted order.
+        #
+        # Creates a constraint that ensures the collection's elements are in ascending order based on their natural
+        # comparison methods.
+        #
+        # @example
+        #   type.being_ordered
+        #   type.validate([1, 2, 3])   # => true
+        #   type.validate([3, 1, 2])   # => false
+        #
+        # @return [self] self for method chaining
+        # @rbs ()-> Behavior
+        def being_sorted
+          # @type self: Object & Behavior
+          constrain :entries, :ordering, description: 'being'
+        end
+        alias being_aranged being_sorted
+        alias being_ordered being_sorted
+        alias being_sequential being_sorted
+        alias aranged being_sorted
+        alias ordered being_sorted
+        alias sorted being_sorted
+        alias sequential being_sorted
+
+        # Validate that the enumerable elements are not in sorted order.
+        #
+        # Creates an inverse ordering constraint that ensures the collection's elements are not in ascending order.
+        #
+        # @example
+        #   type.being_unordered
+        #   type.validate([3, 1, 2])   # => true
+        #   type.validate([1, 2, 3])   # => false
+        #
+        # @return [self] self for method chaining
+        # @rbs ()-> Behavior
+        def being_unsorted
+          # @type self: Object & Behavior
+          ordered = @constraints.prepare :self, :ordering
+          constrain :entries, :not, ordered, concerning: :ordering, description: 'being'
+        end
+        alias being_disordered being_unsorted
+        alias being_unordered being_unsorted
+        alias disordered being_unsorted
+        alias unsorted being_unsorted
+        alias unordered being_unsorted
+
+        # Validate that the enumerable contains specific entries.
+        #
+        # Creates a series of inclusion constraints ensuring the collection contains all specified elements.
+        #
+        # @example
+        #   type.containing(1, 2)
+        #   type.validate([1, 2, 3])   # => true
+        #   type.validate([1, 3])      # => false
+        #
+        # @param entries [Array<Object>] the elements that must be present
+        # @return [self] self for method chaining
+        # @rbs (*untyped entries)-> Behavior
+        def containing(*entries)
+          # @type self: Object & Behavior
+          including = entries.map do |entry|
+            @constraints.prepare :entries, :inclusion, entry
+          end
+          constrain :entries, :and, including, concerning: :entry_inclusion
+        end
+        alias including containing
+
+        # Validate that the enumerable contains a specific last entry.
+        #
+        # Creates an equality constraint on the collection's last entry ensuring it is equal to the specified value.
+        #
+        # @example
+        #   type.having_last_entry(3)
+        #   type.validate([1, 2, 3])   # => true
+        #   type.validate([1, 3, 2])   # => false
+        #
+        # @param literal [Object] the value that must be the last entry
+        # @return [self] self for method chaining
+        # @rbs (untyped literal)-> Behavior
+        def ending_with(literal)
+          # @type self: Object & Behavior
+          constrain :last, :equality, literal, concerning: :last_entry_value, description: 'with last entry'
+        end
+        alias closing_with ending_with
+        alias finishing_with ending_with
+
+        # Validate that the enumerable does not contain specific entries.
+        #
+        # Creates a series of exclusion constraints ensuring the collection does not contain any of the specified
+        # elements.
+        #
+        # @example
+        #   type.excluding(1, 2)
+        #   type.validate([3, 4, 5])   # => true
+        #   type.validate([1, 2, 3])   # => false
+        #
+        # @param entries [Array<Object>] the elements that must not be present
+        # @return [self] self for method chaining
+        # @rbs (*untyped entries)-> Behavior
+        def excluding(*entries)
+          # @type self: Object & Behavior
+          including = entries.map do |entry|
+            @constraints.prepare :entries, :inclusion, entry
+          end
+          constrain :entries, :nor, including, concerning: :entry_exclusion
+        end
+        alias omitting excluding
+
+        # Validate that the enumerable contains elements of a specific type.
+        #
+        # Creates a type constraint on the collection's elements ensuring they are all of the specified type.
+        #
+        # @example
+        #   type.of(String)
+        #   type.validate(['a', 'b', 'c'])   # => true
+        #   type.validate(['a', 1, 'c'])     # => false
+        #
+        # @param type [Class, Module, Behavior] the type that all elements must be
+        # @return [self] self for method chaining
+        # @rbs (Class | Module | Behavior type)-> Behavior
+        def of(type)
+          # @type self: Object & Behavior
+          type = @constraints.prepare :self, :type, type
+          constrain :entries, :all, type, concerning: :entry_type
+        end
+
+        # Validate that the enumerable contains a specific first entry.
+        #
+        # Creates an equality constraint on the collection's first entry ensuring it is equal to the specified value.
+        #
+        # @example
+        #   type.having_first_entry(1)
+        #   type.validate([1, 2, 3])   # => true
+        #   type.validate([2, 3, 1])   # => false
+        #
+        # @param literal [Object] the value that must be the first entry
+        # @return [self] self for method chaining
+        # @rbs (untyped literal)-> Behavior
+        def starting_with(literal)
+          # @type self: Object & Behavior
+          constrain :first, :equality, literal, concerning: :first_entry_value, description: 'with first entry'
+        end
+        alias begining_with starting_with
+        alias leading_with starting_with
+      end
+    end
+  end
+end