delivered 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab93c9434d5e06930f9fa814dfef95849cda9c6b76c611ed54b7c51d1e4856d
-  data.tar.gz: 868e6e469da0d2a07e752f7c35725414a99aa06ab898f13c8b177cf6c2d892f5
+  metadata.gz: 23b613f6dd8b19b06d0ca874c1a4f7408708f18b88e05d53b683693b27a20a04
+  data.tar.gz: 1380e56b87e1fa5b534b5bd6645dc1d965dec1c81021e042c4fc7f031aafdae2
 SHA512:
-  metadata.gz: 1d94413829107f3b7cd6c60d4a28fc9c98abc5649b5dca0987ba88499729798d090563c882630a3be7495d22c99c32011a219c8d819d11429f7b23afb15c1db6
-  data.tar.gz: ac6388a9494a423891d5d9260c42ca7c9e4c90f0d85be89f36e54732aaa0cac0c0797c1947f8d983aa544e2967000e8187925ca60087d3062fe05d10d5fbf072
+  metadata.gz: ef984b3f51256ace952efaac631986a500c121408a42f544f6f9c4c296d2d88e2cc909452232bbdb498b4177ead3b910139205105c4137180c56dfcca2297f28
+  data.tar.gz: 17d2eaeb8cc23bfe69dd3f76b7b33d09d967f0f87d81221209c4b09c6cbd3777ed8ea45d4fd62ad119155a7bd1cd1aba8476677d022a6b24afb23032ff9dd423

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    delivered (0.1.0)
+    delivered (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,18 +1,140 @@
 # 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
+```
+
+#### `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,88 @@
 
 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}` as positional arg #{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]}` as keyword arg :#{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}`, 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,41 @@
+# frozen_string_literal: true
+
+module Delivered
+  class AnyType
+    def initialize(*types)
+      @types = types
+    end
+
+    def ===(value)
+      @types.empty? ? true : @types.any? { |type| type === value }
+    end
+  end
+
+  class NilableType
+    def initialize(type = nil)
+      @type = type
+    end
+
+    def ===(value)
+      (@type.nil? ? true : nil === value) || @type === value
+    end
+  end
+
+  class BooleanType
+    def initialize
+      freeze
+    end
+
+    def ===(value)
+      [true, false].include?(value)
+    end
+  end
+
+  module Types
+    module_function
+
+    def Nilable(type = nil) = NilableType.new(type)
+    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.2.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.2.0
 platform: ruby
 authors:
 - Joel Moss
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-27 00:00:00.000000000 Z
+date: 2024-04-04 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,7 +42,7 @@ 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:
   - - ">="