strict 0.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23b160a9d38c3450223118fcf7c11f7833f1bd25c7f384c966e553e52430e52
-  data.tar.gz: 8588a01fe2783f8ad7955089af408d969e11713309e97db7eaaa38e344d8b070
+  metadata.gz: 2bf58678470f8cc840c19af0f64ce47ea55abe7124779d1b37ebe10707708d41
+  data.tar.gz: 02fb60b1183ab1d5eb90c8438a2271512db588438e75f1f89958e67325788360
 SHA512:
-  metadata.gz: 284acd977a15b2d81a05d91b3dd2bfa3a0cfc9cad3e029cf2c10880020fbbbe23f6f7bfaf3b50d09b23ebc58e78cd65983ea156c7bc1cdd4bbd38337da6efcb6
-  data.tar.gz: f9c133d678e635b1d14dbb46acbcf71538aa9fc7508cfa3d75d47ae21015fef61f097956f6f3e89998b805e2ea16d4777f7c36802fc59e82783645b80525506c
+  metadata.gz: e333d0836e79b87dfe89fbdc88c915506609a815b1bfce94b4432f40cdf87696c94da52294d3410d11faa48de6c2197194f8be1216cc50ccce2fc9871ab543fc
+  data.tar.gz: 14c429b220b1a1c890f164daf50dbda22b86d85659abd1c4a8980abd90785d6c52efc7840af85a75740f2dd928c45861d1244061eb703f5e1461b4cabbe8c2f9

data/.rubocop.yml

@@ -1,9 +1,21 @@
+require:
+  - rubocop-minitest
+  - rubocop-rake
+
 AllCops:
   NewCops: enable
   TargetRubyVersion: 3.1.2
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
+Style/CaseEquality:
+  Enabled: false
 
 Style/Documentation:
   Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Metrics/BlockLength:
+   Exclude:
+    - "test/**/*"
+    - "*.gemspec"

data/Gemfile.lock

@@ -1,22 +1,31 @@
 PATH
   remote: .
   specs:
-    strict (0.0.0)
+    strict (1.1.0)
       zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    debug (1.6.1)
+      irb (>= 1.3.6)
+      reline (>= 0.3.1)
     gem-release (2.2.2)
+    io-console (0.5.11)
+    irb (1.4.1)
+      reline (>= 0.3.0)
     json (2.6.2)
     minitest (5.16.2)
+    minitest-spec-context (0.0.4)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.0)
+    reline (0.3.1)
+      io-console (~> 0.5)
     rexml (3.2.5)
     rubocop (1.36.0)
       json (~> 2.3)
@@ -30,19 +39,27 @@ GEM
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.21.0)
       parser (>= 3.1.1.0)
+    rubocop-minitest (0.22.2)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.3.0)
-    zeitwerk (2.6.0)
+    zeitwerk (2.6.1)
 
 PLATFORMS
   arm64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
+  debug (>= 1.0.0)
   gem-release (~> 2.2)
   minitest (~> 5.0)
+  minitest-spec-context (~> 0.0.4)
   rake (~> 13.0)
   rubocop (~> 1.21)
+  rubocop-minitest (~> 0.22)
+  rubocop-rake (~> 0.6)
   strict!
 
 BUNDLED WITH

data/README.md

@@ -1,22 +1,177 @@
 # Strict
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/strict`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Strict provides a means to strictly validate instantiation of values, instantiation and attribute assignment of objects, and method calls at runtime.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add strict
+```sh
+$ bundle add strict
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install strict
+```sh
+$ gem install strict
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### `Strict::Value`
+
+```rb
+class Money
+  include Strict::Value
+
+  attributes do
+    amount_in_cents Integer
+    currency AnyOf("USD", "CAD"), default: "USD"
+  end
+end
+
+Money.new(amount_in_cents: 100_00)
+# => #<Money amount_in_cents=100_00 currency="USD">
+
+Money.new(amount_in_cents: 100_00, currency: "CAD")
+# => #<Money amount_in_cents=100_00 currency="CAD">
+
+Money.new(amount_in_cents: 100.00)
+# => Strict::InitializationError
+
+Money.new(amount_in_cents: 100_00).with(amount_in_cents: 200_00)
+# => #<Money amount_in_cents=200_00 currency="USD">
+
+Money.new(amount_in_cents: 100_00).amount_in_cents = 50_00
+# => NoMethodError
+
+Money.new(amount_in_cents: 100_00) == Money.new(amount_in_cents: 100_00)
+# => true
+```
+
+### `Strict::Object`
+
+```rb
+class Stateful
+  include Strict::Object
+
+  attributes do
+    some_state String
+    dependency Anything(), default: nil
+  end
+end
+
+Stateful.new(some_state: "123")
+# => #<Stateful some_state="123" dependency=nil>
+
+Stateful.new(some_state: "123").with(some_state: "456")
+# => NoMethodError
+
+Stateful.new(some_state: "123").some_state = "456"
+# => "456"
+# => #<Stateful some_state="456" dependency=nil>
+
+Stateful.new(some_state: "123").some_state = 456
+# => Strict::AssignmentError
+
+Stateful.new(some_state: "123") == Stateful.new(some_state: "123")
+# => false
+```
+
+### `Strict::Method`
+
+```rb
+class UpdateEmail
+  extend Strict::Method
+
+  sig do
+    user_id String, coerce: ->(value) { value.to_s }
+    email String
+    returns AnyOf(true, nil)
+  end
+  def call(user_id:, email:)
+    # contrived logic
+    user_id == email
+  end
+end
+
+UpdateEmail.new.call(user_id: 123, email: "123")
+# => true
+
+UpdateEmail.new.call(user_id: "123", email: "123")
+# => true
+
+UpdateEmail.new.call(user_id: "123", email: 123)
+# => Strict::MethodCallError
+
+UpdateEmail.new.call(user_id: "123", email: "456")
+# => Strict::MethodReturnError
+```
+
+### `Strict::Interface`
+
+```rb
+class Storage
+  extend Strict::Interface
+
+  expose(:write) do
+    key String
+    contents String
+    returns Boolean()
+  end
+
+  expose(:read) do
+    key String
+    returns AnyOf(String, nil)
+  end
+end
+
+module Storages
+  class Memory
+    def initialize
+      @storage = {}
+    end
+
+    def write(key:, contents:)
+      storage[key] = contents
+      true
+    end
+
+    def read(key:)
+      storage[key]
+    end
+
+    private
+
+    attr_reader :storage
+  end
+end
+
+storage = Storage.new(Storages::Memory.new)
+# => #<Storage implementation=#<Storages::Memory>>
+
+storage.write(key: "some/path/to/file.rb", contents: "Hello")
+# => true
+
+storage.write(key: "some/path/to/file.rb", contents: {})
+# => Strict::MethodCallError
+
+storage.read(key: "some/path/to/file.rb")
+# => "Hello"
+
+storage.read(key: "some/path/to/other.rb")
+# => nil
+
+module Storages
+  class Wat
+    def write(key:)
+    end
+  end
+end
+
+storage = Storage.new(Storages::Wat.new)
+# => Strict::ImplementationDoesNotConformError
+```
 
 ## Development
 
@@ -35,3 +190,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the Strict project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kylekthompson/strict/blob/main/CODE_OF_CONDUCT.md).
+
+## Credit
+
+I can't thank [Tom Dalling](https://github.com/tomdalling) enough for his excellent [ValueSemantics](https://github.com/tomdalling/value_semantics) gem. Strict is heavily inspired and influenced by Tom's work and has some borrowed concepts and code.

data/lib/strict/accessor/attributes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Strict
+  module Accessor
+    module Attributes
+      def attributes(&block)
+        block ||= -> {}
+        configuration = Strict::Attributes::Dsl.run(&block)
+        include Module.new(configuration)
+        include Strict::Attributes::Instance
+        extend Strict::Attributes::Class
+      end
+    end
+  end
+end

data/lib/strict/accessor/module.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Strict
+  module Accessor
+    class Module < ::Module
+      attr_reader :configuration
+
+      # rubocop:disable Metrics/MethodLength
+      def initialize(configuration)
+        super()
+
+        @configuration = configuration
+        const_set(Strict::Attributes::Class::CONSTANT, configuration)
+        configuration.attributes.each do |attribute|
+          module_eval(
+            "def #{attribute.name} = #{attribute.instance_variable}", # def name = @instance_variable
+            __FILE__,
+            __LINE__ - 2
+          )
+
+          module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            def #{attribute.name}=(value)                                         # def name=(value)
+              attribute = self.class.strict_attributes.named!(:#{attribute.name}) #   attribute = self.class.strict_attributes.named!(:name)
+              value = attribute.coerce(value, for_class: self.class)              #   value = attribute.coerce(value, for_class: self.class)
+              if attribute.valid?(value)                                          #   if attribute.valid?(value)
+                #{attribute.instance_variable} = value                            #     @instance_variable = value
+              else                                                                #   else
+                raise Strict::AssignmentError.new(                                #     raise Strict::AssignmentError.new(
+                  assignable_class: self.class,                                   #       assignable_class: self.class,
+                  invalid_attribute: attribute,                                   #       invalid_attribute: attribute,
+                  value:                                                          #       value:
+                )                                                                 #     )
+              end                                                                 #   end
+            end                                                                   # end
+          RUBY
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def inspect
+        "#<#{self.class} (#{configuration.attributes.map(&:name).join(', ')})>"
+      end
+    end
+  end
+end

data/lib/strict/assignment_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Strict
+  class AssignmentError < Error
+    attr_reader :invalid_attribute, :value
+
+    def initialize(assignable_class:, invalid_attribute:, value:)
+      super(message_from(assignable_class:, invalid_attribute:, value:))
+
+      @invalid_attribute = invalid_attribute
+      @value = value
+    end
+
+    private
+
+    def message_from(assignable_class:, invalid_attribute:, value:)
+      details = invalid_attribute_message_from(invalid_attribute, value)
+      "Assignment to #{invalid_attribute.name} of #{assignable_class} failed because:\n#{details}"
+    end
+
+    def invalid_attribute_message_from(invalid_attribute, value)
+      "  - got #{value.inspect}, expected #{invalid_attribute.validator.inspect}"
+    end
+  end
+end

data/lib/strict/attribute.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Strict
+  class Attribute
+    NOT_PROVIDED = ::Object.new.freeze
+
+    class << self
+      def make(name, validator = Validators::Anything.instance, coerce: false, **defaults)
+        unless valid_defaults?(**defaults)
+          raise ArgumentError, "Only one of 'default', 'default_value', or 'default_generator' can be provided"
+        end
+
+        new(name: name.to_sym, validator:, default_generator: make_default_generator(**defaults), coercer: coerce)
+      end
+
+      private
+
+      def valid_defaults?(default: NOT_PROVIDED, default_value: NOT_PROVIDED, default_generator: NOT_PROVIDED)
+        defaults_provided = [default, default_value, default_generator].count do |default_option|
+          !default_option.equal?(NOT_PROVIDED)
+        end
+
+        defaults_provided <= 1
+      end
+
+      def make_default_generator(default: NOT_PROVIDED, default_value: NOT_PROVIDED, default_generator: NOT_PROVIDED)
+        if !default.equal?(NOT_PROVIDED)
+          default.respond_to?(:call) ? default : -> { default }
+        elsif !default_value.equal?(NOT_PROVIDED)
+          -> { default_value }
+        elsif !default_generator.equal?(NOT_PROVIDED)
+          default_generator
+        else
+          NOT_PROVIDED
+        end
+      end
+    end
+
+    attr_reader :name, :validator, :default_generator, :coercer, :instance_variable
+
+    def initialize(name:, validator:, default_generator:, coercer:)
+      @name = name.to_sym
+      @validator = validator
+      @default_generator = default_generator
+      @coercer = coercer
+      @optional = !default_generator.equal?(NOT_PROVIDED)
+      @instance_variable = "@#{name.to_s.chomp('!').chomp('?')}"
+    end
+
+    def optional?
+      @optional
+    end
+
+    def valid?(value)
+      validator === value
+    end
+
+    def coerce(value, for_class:)
+      return value unless coercer
+
+      case coercer
+      when Symbol
+        for_class.public_send(coercer, value)
+      when true
+        for_class.public_send("coerce_#{name}", value)
+      else
+        coercer.call(value)
+      end
+    end
+  end
+end

data/lib/strict/attributes/class.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    module Class
+      CONSTANT = :STRICT_INTERNAL_ATTRIBUTES_CONFIGURATION__
+
+      def strict_attributes
+        self::STRICT_INTERNAL_ATTRIBUTES_CONFIGURATION__
+      end
+
+      def coercer
+        Coercer.new(self)
+      end
+    end
+  end
+end

data/lib/strict/attributes/coercer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    class Coercer
+      attr_reader :attributes_class
+
+      def initialize(attributes_class)
+        @attributes_class = attributes_class
+      end
+
+      def call(value)
+        return value if value.nil? || !value.respond_to?(:to_h)
+
+        coerce(value.to_h)
+      end
+
+      private
+
+      NOT_PROVIDED = ::Object.new.freeze
+
+      def coerce(hash)
+        attributes_class.new(
+          **attributes_class.strict_attributes.each_with_object({}) do |attribute, attributes|
+            value = hash.fetch(attribute.name) { hash.fetch(attribute.name.to_s, NOT_PROVIDED) }
+            attributes[attribute.name] = value unless value.equal?(NOT_PROVIDED)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/strict/attributes/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Strict
+  module Attributes
+    class Configuration
+      include Enumerable
+      extend Forwardable
+
+      class UnknownAttributeError < Error
+        attr_reader :attribute_name
+
+        def initialize(attribute_name:)
+          super(message_from(attribute_name:))
+
+          @attribute_name = attribute_name
+        end
+
+        private
+
+        def message_from(attribute_name:)
+          "Strict tried to find an attribute named #{attribute_name} but was unable. " \
+            "It's likely this in an internal bug, feel free to open an issue at #{Strict::ISSUE_TRACKER} for help."
+        end
+      end
+
+      def_delegator :attributes, :each
+
+      attr_reader :attributes
+
+      def initialize(attributes:)
+        @attributes = attributes
+        @attributes_index = attributes.to_h { |a| [a.name, a] }
+      end
+
+      def named!(name)
+        attributes_index.fetch(name) { raise UnknownAttributeError.new(attribute_name: name) }
+      end
+
+      private
+
+      attr_reader :attributes_index
+    end
+  end
+end

data/lib/strict/attributes/dsl.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    class Dsl < BasicObject
+      class << self
+        def run(&)
+          dsl = new
+          dsl.instance_eval(&)
+          ::Strict::Attributes::Configuration.new(attributes: dsl.__strict_dsl_internal_attributes.values)
+        end
+      end
+
+      include ::Strict::Dsl::Coercible
+      include ::Strict::Dsl::Validatable
+
+      attr_reader :__strict_dsl_internal_attributes
+
+      def initialize
+        @__strict_dsl_internal_attributes = {}
+      end
+
+      def strict_attribute(*args, **kwargs)
+        attribute = ::Strict::Attribute.make(*args, **kwargs)
+        __strict_dsl_internal_attributes[attribute.name] = attribute
+        nil
+      end
+
+      def method_missing(name, *args, **kwargs)
+        if respond_to_missing?(name)
+          strict_attribute(name, *args, **kwargs)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, _include_private = nil)
+        first_letter = method_name.to_s.each_char.first
+        first_letter.eql?(first_letter.downcase)
+      end
+    end
+  end
+end

data/lib/strict/attributes/instance.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Strict
+  module Attributes
+    module Instance
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def initialize(**attributes)
+        remaining_attributes = Set.new(attributes.keys)
+        invalid_attributes = nil
+        missing_attributes = nil
+
+        self.class.strict_attributes.each do |attribute|
+          if remaining_attributes.delete?(attribute.name)
+            value = attributes.fetch(attribute.name)
+          elsif attribute.optional?
+            value = attribute.default_generator.call
+          else
+            missing_attributes ||= []
+            missing_attributes << attribute.name
+            next
+          end
+
+          value = attribute.coerce(value, for_class: self.class)
+          if attribute.valid?(value)
+            instance_variable_set(attribute.instance_variable, value)
+          else
+            invalid_attributes ||= {}
+            invalid_attributes[attribute] = value
+          end
+        end
+
+        return if remaining_attributes.none? && invalid_attributes.nil? && missing_attributes.nil?
+
+        raise InitializationError.new(
+          initializable_class: self.class,
+          remaining_attributes:,
+          invalid_attributes:,
+          missing_attributes:
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def to_h
+        self.class.strict_attributes.to_h do |attribute|
+          [attribute.name, public_send(attribute.name)]
+        end
+      end
+
+      def inspect
+        if self.class.strict_attributes.any?
+          "#<#{self.class} #{to_h.map { |key, value| "#{key}=#{value.inspect}" }.join(' ')}>"
+        else
+          "#<#{self.class}>"
+        end
+      end
+
+      def pretty_print(pp)
+        pp.object_group(self) do
+          to_h.each do |key, value|
+            pp.breakable
+            pp.text("#{key}=")
+            pp.pp(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/strict/coercers/array.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Strict
+  module Coercers
+    class Array
+      attr_reader :element_coercer
+
+      def initialize(element_coercer = nil)
+        @element_coercer = element_coercer
+      end
+
+      def call(value)
+        return value if value.nil? || !value.respond_to?(:to_a)
+
+        array = value.to_a
+        return array unless element_coercer
+
+        array.map { |element| element_coercer.call(element) }
+      end
+    end
+  end
+end