delivered 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab93c9434d5e06930f9fa814dfef95849cda9c6b76c611ed54b7c51d1e4856d
-  data.tar.gz: 868e6e469da0d2a07e752f7c35725414a99aa06ab898f13c8b177cf6c2d892f5
+  metadata.gz: c2cc2a244302acba122bf449caa221233453955568ca1a7c42f9a4c66e75093a
+  data.tar.gz: 2c6033b4adee7756b8fb7bbb9ff0cac83bbe7f42e35220eb9a24857c17e2aa7e
 SHA512:
-  metadata.gz: 1d94413829107f3b7cd6c60d4a28fc9c98abc5649b5dca0987ba88499729798d090563c882630a3be7495d22c99c32011a219c8d819d11429f7b23afb15c1db6
-  data.tar.gz: ac6388a9494a423891d5d9260c42ca7c9e4c90f0d85be89f36e54732aaa0cac0c0797c1947f8d983aa544e2967000e8187925ca60087d3062fe05d10d5fbf072
+  metadata.gz: 3adf4d4bb048a39a00e331e598814998fffe28673702d08bba181cd574f521b3f2d164725c5fe61d349c85c960c32a59d98bb8855ff0f26db6ad5bd74123ae4e
+  data.tar.gz: 735bde97671a2e2d69238b5363de35971ecb1a7ab4003e2352c560231bd461b712a3e652bd01c9b02cf067d5d8b2a856baf6b8709621c5f8e34b0eb94c692e9f

data/Gemfile.lock

@@ -1,24 +1,24 @@
 PATH
   remote: .
   specs:
-    delivered (0.1.0)
+    delivered (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     amazing_print (1.6.0)
     ast (2.4.2)
-    debug (1.9.1)
+    debug (1.9.2)
       irb (~> 1.10)
       reline (>= 0.3.8)
     io-console (0.7.2)
-    irb (1.12.0)
-      rdoc
+    irb (1.13.1)
+      rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.7.1)
+    json (2.7.2)
     language_server-protocol (3.17.0.3)
     parallel (1.24.0)
-    parser (3.3.0.5)
+    parser (3.3.1.0)
       ast (~> 2.4.1)
       racc
     psych (5.1.2)
@@ -27,11 +27,12 @@ GEM
     rainbow (3.1.1)
     rdoc (6.6.3.1)
       psych (>= 4.0.0)
-    regexp_parser (2.9.0)
-    reline (0.5.0)
+    regexp_parser (2.9.2)
+    reline (0.5.7)
       io-console (~> 0.5)
-    rexml (3.2.6)
-    rubocop (1.62.1)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
+    rubocop (1.63.5)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -42,11 +43,12 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.2)
-      parser (>= 3.3.0.4)
+    rubocop-ast (1.31.3)
+      parser (>= 3.3.1.0)
     ruby-progressbar (1.13.0)
     stringio (3.1.0)
-    sus (0.24.6)
+    strscan (3.1.0)
+    sus (0.25.0)
     unicode-display_width (2.5.0)
 
 PLATFORMS

data/README.md

@@ -1,18 +1,149 @@
 # Delivered: Simple runtime type checking for Ruby method signatures
 
+> Signed, Sealed, Delivered 🎹
+
 Delivered gives you the ability to define method signatures in Ruby, and have them checked at
 runtime. This is useful for ensuring that your methods are being called with the correct arguments,
-and for providing better error messages when they are not.
+and for providing better error messages when they are not. It also serves as a nice way of
+documenting your methods using actual code instead of comments.
+
+## Usage
 
 Simply define a method signature using the `sig` method directly before the method to be checked,
-and Delivered will check that the method is being called with the correct arguments and types. it
-can alos chreck the return value of the method.
+and Delivered will check that the method is being called with the correct arguments and types.
 
 ```ruby
 class User
-  sig String, age: Integer, returns: String
+  extend Delivered::Signature
+
+  sig String, age: Integer
   def create(name, age:)
     "User #{name} created with age #{age}"
   end
 end
 ```
+
+If an invalid argument is given to `User#create`, for example, if `age` is a `String` instead of
+the required `Integer`, a `Delivered::ArgumentError` exception will be raised.
+
+### Return Types
+
+You can also check the return value of the method by passing a Hash with an Array as the key, and
+the value as the return type to check.
+
+```ruby
+sig [String, age: Integer] => String
+def create(name, age:)
+  "User #{name} created with age #{age}"
+end
+```
+
+Or by placing the return type in a block to `sig`.
+
+```ruby
+sig(String, age: Integer) { String }
+def create(name, age:)
+  "User #{name} created with age #{age}"
+end
+```
+
+### Delivered Types
+
+As well as Ruby's native types (ie. `String`, `Integer`, etc.), _Delivered_ provides a couple of
+extra types in `Delivered::Types`.
+
+You can call these directly with `Delivered::Types.Boolean`, or for brevity, assign
+`Delivered::Types` to `T` in your classes:
+
+```ruby
+class User
+  extend Delivered::Signature
+  T = Delivered::Types
+end
+```
+
+The following examples all use the `T` alias, and assumes the above.
+
+#### `Boolean`
+
+Value **MUST** be `true` or `false`. Does not support "truthy" or "falsy" values.
+
+```ruby
+sig validate: T.Boolean
+def create(validate:); end
+```
+
+#### `RespondTo`
+
+Value **MUST** be respond to the given method(s).
+
+```ruby
+sig name: T.RespondTo(:to_s)
+def create(name:); end
+```
+
+#### `Any`
+
+Value **MUST** be any of the given list of values, that is, the value must be one of the given list.
+
+```ruby
+sig T.Any(:male, :female)
+def create(gender); end
+```
+
+If no type is given, the value **CAN** be any type or value.
+
+```ruby
+sig save: T.Any
+def create(save: nil); end
+```
+
+You can also pass `nil` to allow a nil value alongside any other types you provide.
+
+```ruby
+sig T.Any(String, nil)
+def create(save = nil); end
+```
+
+#### `Nilable`
+
+When a type is given, the value **MUST** be nil **OR** of the given type.
+
+```ruby
+sig save: T.Nilable(String)
+def create(save: nil); end
+
+sig T.Nilable(String)
+def update(name = nil); end
+```
+
+If no type is given, the value **CAN** be nil. This essentially allows any value, including nil.
+
+```ruby
+sig save: T.Nilable
+def create(save: nil); end
+```
+
+You may notice that `Nilable` is interchangeable with `Any`. The following are equivilent:
+
+```ruby
+sig save: T.Nilable
+def create(save: nil); end
+```
+
+```ruby
+sig save: T.Any
+def create(save: nil); end
+```
+
+As are these:
+
+```ruby
+sig T.Nilable(String)
+def update(name = nil); end
+```
+
+```ruby
+sig T.Any(String, nil)
+def update(name = nil); end
+```

data/delivered.gemspec

@@ -11,7 +11,11 @@ Gem::Specification.new do |s|
   s.homepage      = 'https://github.com/joelmoss/delivered'
   s.licenses      = ['MIT']
   s.summary       = 'Simple runtime type checking for Ruby method signatures'
-  s.required_ruby_version = '>= 3.2'
+  s.required_ruby_version = '>= 3.1'
+
+  s.metadata['homepage_uri'] = s.homepage
+  s.metadata['source_code_uri'] = s.homepage
+  s.metadata['changelog_uri'] = "#{s.homepage}/releases"
 
   s.files         = Dir.glob('{bin/*,lib/**/*,[A-Z]*}')
   s.platform      = Gem::Platform::RUBY

data/lib/delivered/signature.rb

@@ -2,32 +2,89 @@
 
 module Delivered
   module Signature
-    NULL = Object.new
+    def sig(*sig_args, **sig_kwargs, &return_blk)
+      # ap [sig_args, sig_kwargs, return_blk]
+
+      # Block return
+      returns = return_blk&.call
+
+      # Hashrocket return
+      if sig_kwargs.keys[0].is_a?(Array)
+        unless returns.nil?
+          raise Delivered::ArgumentError,
+                'Cannot mix block and hash for return type. Use one or the other.', caller
+        end
+
+        returns = sig_kwargs.values[0]
+        sig_args = sig_kwargs.keys[0]
+        sig_kwargs = sig_args.pop if sig_args.last.is_a?(Hash)
+      end
+
+      # ap [sig_args, sig_kwargs, returns]
 
-    def sig(*sig_args, returns: NULL, **sig_kwargs)
       meta = class << self; self; end
+      sig_check = lambda do |klass, class_method, name, *args, **kwargs, &block| # rubocop:disable Metrics/BlockLength
+        cname = if class_method
+                  "#{klass.name}.#{name}"
+                else
+                  "#{klass.class.name}##{name}"
+                end
+
+        sig_args.each.with_index do |arg, i|
+          args[i] => ^arg
+        rescue NoMatchingPatternError => e
+          raise Delivered::ArgumentError,
+                "`#{cname}` expected #{arg.inspect} as argument #{i}, but received " \
+                "`#{args[i].inspect}`",
+                caller, cause: e
+        end
+
+        kwargs.each do |key, value|
+          value => ^(sig_kwargs[key])
+        rescue NoMatchingPatternError => e
+          raise Delivered::ArgumentError,
+                "`#{cname}` expected #{sig_kwargs[key].inspect} as keyword argument :#{key}, " \
+                "but received `#{value.inspect}`",
+                caller, cause: e
+        end
+
+        result = if block
+                   klass.send(:"__#{name}", *args, **kwargs, &block)
+                 else
+                   klass.send(:"__#{name}", *args, **kwargs)
+                 end
+
+        begin
+          result => ^returns unless returns.nil?
+        rescue NoMatchingPatternError => e
+          raise Delivered::ArgumentError,
+                "`#{cname}` expected to return #{returns.inspect}, " \
+                "but returned `#{result.inspect}`",
+                caller, cause: e
+        end
+
+        result
+      end
+
       meta.send :define_method, :method_added do |name|
         meta.send :remove_method, :method_added
+        meta.send :remove_method, :singleton_method_added
 
         alias_method :"__#{name}", name
         define_method name do |*args, **kwargs, &block|
-          sig_args.each.with_index do |arg, i|
-            args[i] => ^arg
-          end
-
-          kwargs.each do |key, value|
-            value => ^(sig_kwargs[key])
-          end
+          sig_check.call(self, false, name, *args, **kwargs, &block)
+        end
+      end
 
-          result = if block
-                     send(:"__#{name}", *args, **kwargs, &block)
-                   else
-                     send(:"__#{name}", *args, **kwargs)
-                   end
+      meta.send :define_method, :singleton_method_added do |name|
+        next if name == :singleton_method_added
 
-          result => ^returns if returns != NULL
+        meta.send :remove_method, :singleton_method_added
+        meta.send :remove_method, :method_added
 
-          result
+        meta.alias_method :"__#{name}", name
+        define_singleton_method name do |*args, **kwargs, &block|
+          sig_check.call(self, true, name, *args, **kwargs, &block)
         end
       end
     end

data/lib/delivered/types.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Delivered
+  class AnyType
+    def initialize(*types)
+      @types = types
+    end
+
+    def inspect = "Any(#{@types.map(&:inspect).join(', ')})"
+
+    def ===(value)
+      @types.empty? ? true : @types.any? { |type| type === value }
+    end
+  end
+
+  class RespondToType
+    def initialize(*methods)
+      @methods = methods
+    end
+
+    def inspect = "RespondTo(#{@methods.map(&:inspect).join(', ')})"
+
+    def ===(value)
+      @methods.all? { |m| value.respond_to?(m) }
+    end
+  end
+
+  class NilableType
+    def initialize(type = nil)
+      @type = type
+    end
+
+    def inspect = "Nilable(#{@type&.inspect || 'Any'})"
+
+    def ===(value)
+      (@type.nil? ? true : nil === value) || @type === value
+    end
+  end
+
+  class BooleanType
+    def initialize
+      freeze
+    end
+
+    def inspect = 'Boolean'
+
+    def ===(value)
+      [true, false].include?(value)
+    end
+  end
+
+  module Types
+    module_function
+
+    def Nilable(type = nil) = NilableType.new(type)
+    def RespondTo(*methods) = RespondToType.new(*methods)
+    def Any(*types) = AnyType.new(*types)
+    def Boolean = BooleanType.new
+  end
+end

data/lib/delivered/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Delivered
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/delivered.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
 module Delivered
+  class ArgumentError < ArgumentError
+  end
+
   autoload :Signature, 'delivered/signature'
+  autoload :Types, 'delivered/types'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: delivered
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Joel Moss
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-27 00:00:00.000000000 Z
+date: 2024-05-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -24,11 +24,15 @@ files:
 - delivered.gemspec
 - lib/delivered.rb
 - lib/delivered/signature.rb
+- lib/delivered/types.rb
 - lib/delivered/version.rb
 homepage: https://github.com/joelmoss/delivered
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://github.com/joelmoss/delivered
+  source_code_uri: https://github.com/joelmoss/delivered
+  changelog_uri: https://github.com/joelmoss/delivered/releases
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -38,14 +42,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Simple runtime type checking for Ruby method signatures