praxis 2.0.pre.21 → 2.0.pre.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22211954ff9fa77a0667e1daf3ae00b30d1d599cd5a25b65547321295e5a2fcb
-  data.tar.gz: 3ec2f9c7f2cd9d261f09675a25ca5211131c65d58cc088a539f60f273d5ac207
+  metadata.gz: fcf3359dc0ac9062c61efc934673d9bf5dfdda43e5abfbc9abc41d3030a7a00e
+  data.tar.gz: 04ffe07b27222f714b8da5e756cc9e1733b76d066a9e1bf5a3d15358dc7e6662
 SHA512:
-  metadata.gz: d46f5cd5b91786467262f2baf3e2e60d27431f3b01ac7d674508f66b33046cb26b6489541eb55324354762964f017dc0e448f69d895dfc7804149e87f57b3b0b
-  data.tar.gz: 957d3f7d32a54f8990e1697a6e6c8182042f15879ef0f8689298ca751b5e0fc5eb64a9f530064066d8722f41b57ddf014889736c5959097c013759ba911beddd
+  metadata.gz: f90af4ae85f4170a850d7d7637758c0c2d878271befa2fe437da8c994ac78657eebd28831bb0945a74ca48aa93a91d42e8b734fd70f3996984e427ad6850a7ae
+  data.tar.gz: b8eaa60ce2ba599b94f4b844339df8501ca295f3e1efb9a0f5dd38b9c4551aa64f108ba3a28913d06a22748dab11fee5c4bd8f9cfb8d2e85b1c456fb3284a5b3

data/.travis.yml

@@ -3,7 +3,7 @@ language: ruby
 rvm:
   - 2.6
   - 2.7
-  # - 3.1 # Not available in TravisCI out of the box yet
+  - 3.1 # Not available in TravisCI out of the box yet
 script:
   - bundle exec rspec spec
 branches:

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## next
 
+## 2.0.pre.22
+  * Introduced Resource callbacks (an includeable concern). Callbacks allow you to define methods or blocks to be executed `before`, `after` or `around` any existing method in the resource. Class-level callbacks are defined with `self.xxxxx`. These methods will be executed within the instance of the resource (i.e., in the same context of the original) and must be defined with the same parameter signature. For around methods, only blocks can be used, and to call the original (inner) one, one needs to yield.
+  * Introduced QueryMethods for resources (an includeable concern). QueryMethods expose handy querying methods (`.get`, `.get!`, `.all`, `.first` and `.last` ) which will reach into the underlying ORM (i.e., right now, only ActiveModelCompat is supported) to perform the desired loading of data (and subsequent wrapping of results in resource instances).
+    * For ActiveRecord `.get` takes a condition hash that will translate to `.find_by`, and `.all` gets a condition hash that will translate to `.where`. 
+    * `.get!` is a `.get` but that will raise a `Praxis::Mapper::ResourceNotFound` exception if nothing was found.
+    * There is an `.including(<spec>)` function that can be use to preload the underlying associations. I.e., the `<spec>` argument will translate to `.includes(<spec>)` in ActiveRecord.
+  * Introduced method signatures and validations for resources.
+    * One can define a method signature with the `signature(<name>)` stanza, passing a block defining Attributor parameters. For instance method signatures, the `<name>` is just a symbol with the name of the method. For class level methods use a string, and prepend `self.` to it (i.e., `self.create`).
+    * Signatures can only work for methods that either have a single argument (taken as a whole hash), or that have only keyword arguments (i.e., no mixed args and kwargs). It would be basically impossible to validate that combo against an Attributor Struct.
+    * The calls to typed methods will be intercepted (using an around callback), and the incoming parameters will be validated against the Attributor Struct defined in the siguature, coerced if necessary and passed onto the original method. If the incoming parameters fail validation, a `IncompatibleTypeForMethodArguments` exception will be thrown.
+
 ## 2.0.pre.21
   * Fix nullable attribute in OpenApi generation
 ## 2.0.pre.20

data/lib/praxis/mapper/active_model_compat.rb

@@ -80,6 +80,27 @@ module Praxis
           end
         end
 
+        # Compatible reader accessors
+        def _get(condition)
+          find_by(condition)
+        end
+
+        def _all(conditions = {})
+          where(conditions)
+        end
+
+        def _add_includes(base, includes)
+          base.includes(includes) # includes(nil) seems to have no effect
+        end
+
+        def _first
+          first
+        end
+
+        def _last
+          last
+        end
+
         private
 
         def local_columns_used_for_the_association(type, assoc_reflection)

data/lib/praxis/mapper/resource.rb

@@ -4,6 +4,15 @@
 # Once that is complete, the data set is iterated and a resultant view is generated.
 module Praxis
   module Mapper
+    class ResourceNotFound < RuntimeError
+      attr_reader :type, :id
+
+      def initialize(type:, id: nil)
+        @type = type
+        @id = id
+      end
+    end
+
     class Resource
       extend Praxis::Finalizable
 
@@ -58,6 +67,7 @@ module Praxis
         finalize_resource_delegates
         define_model_accessors
 
+        hookup_callbacks
         super
       end
 
@@ -79,6 +89,39 @@ module Praxis
         end
       end
 
+      def self.hookup_callbacks
+        return unless ancestors.include?(Praxis::Mapper::Resources::Callbacks)
+
+        instance_module = nil
+        class_module = nil
+
+        affected_methods = (before_callbacks.keys + after_callbacks.keys + around_callbacks.keys).uniq
+        affected_methods&.each do |method|
+          calls = {}
+          calls[:before] = before_callbacks[method] if before_callbacks.key?(method)
+          calls[:around] = around_callbacks[method] if around_callbacks.key?(method)
+          calls[:after] = after_callbacks[method] if after_callbacks.key?(method)
+
+          if method.start_with?('self.')
+            # Look for a Class method
+            simple_name = method.to_s.gsub(/^self./, '').to_sym
+            raise "Error building callback: Class-level method #{method} is not defined in class #{name}" unless methods.include?(simple_name)
+
+            class_module ||= Module.new
+            create_override_module(mod: class_module, method: method(simple_name), calls: calls)
+          else
+            # Look for an instance method
+            raise "Error building callback: Instance method #{method} is not defined in class #{name}" unless method_defined?(method)
+
+            instance_module ||= Module.new
+            create_override_module(mod: instance_module, method: instance_method(method), calls: calls)
+          end
+        end
+        # Prepend the created instance and/or class modules if there were any functions in them
+        prepend instance_module if instance_module
+        singleton_class.send(:prepend, class_module) if class_module
+      end
+
       def self.for_record(record)
         return record._resource if record._resource
 
@@ -184,8 +227,11 @@ module Praxis
       end
 
       def self.define_accessor(name)
-        ivar_name = if name.to_s =~ /\?/
+        ivar_name = case name.to_s
+                    when /\?/
                       "is_#{name.to_s[0..-2]}"
+                    when /!/
+                      "#{name.to_s[0..-2]}_bang"
                     else
                       name.to_s
                     end
@@ -250,6 +296,7 @@ module Praxis
       def reload
         clear_memoization
         reload_record
+        self
       end
 
       def clear_memoization
@@ -275,6 +322,81 @@ module Praxis
           super
         end
       end
+
+      # Defines a 'proxy' method in the given module (mod), so it can then be prepended
+      # There are mostly 3 flavors, which dictate how to define the procs (to make sure we play nicely
+      # with ruby's arguments and all). Method with only args, with only kwords, and with both
+      # Note: if procs could be defined with the (...) syntax, this could be more DRY and simple...
+      def self.create_override_module(mod:, method:, calls:)
+        has_args = method.parameters.any? { |(type, _)| %i[req opt rest].include?(type) }
+        has_kwargs = method.parameters.any? { |(type, _)| %i[keyreq keyrest].include?(type) }
+
+        mod.class_eval do
+          if has_args && has_kwargs
+            # Setup the method to take both args and  kwargs
+            define_method(method.name.to_sym) do |*args, **kwargs|
+              calls[:before]&.each do |target|
+                target.is_a?(Symbol) ? send(target, *args, **kwargs) : instance_exec(*args, **kwargs, &target)
+              end
+
+              orig_call = proc { |*a, **kw| super(*a, **kw) }
+              around_chain = calls[:around].inject(orig_call) do |inner, target|
+                proc { |*a, **kw| send(target, *a, **kw, &inner) }
+              end
+              result = if calls[:around].presence
+                         around_chain.call(*args, **kwargs)
+                       else
+                         super(*args, **kwargs)
+                       end
+              calls[:after]&.each do |target|
+                target.is_a?(Symbol) ? send(target, *args, **kwargs) : instance_exec(*args, **kwargs, &target)
+              end
+              result
+            end
+          elsif has_kwargs && !has_args
+            # Setup the method to only take kwargs
+            define_method(method.name.to_sym) do |**kwargs|
+              calls[:before]&.each do |target|
+                target.is_a?(Symbol) ? send(target, **kwargs) : instance_exec(**kwargs, &target)
+              end
+              orig_call = proc { |**kw| super(**kw) }
+              around_chain = calls[:around].inject(orig_call) do |inner, target|
+                proc { |**kw| send(target, **kw, &inner) }
+              end
+              result = if calls[:around].presence
+                         around_chain.call(**kwargs)
+                       else
+                         super(**kwargs)
+                       end
+              calls[:after]&.each do |target|
+                target.is_a?(Symbol) ? send(target, **kwargs) : instance_exec(**kwargs, &target)
+              end
+              result
+            end
+          else
+            # Setup the method to only take args
+            define_method(method.name.to_sym) do |*args|
+              calls[:before]&.each do |target|
+                target.is_a?(Symbol) ? send(target, *args) : instance_exec(*args, &target)
+              end
+              orig_call = proc { |*a| super(*a) }
+              around_chain = calls[:around].inject(orig_call) do |inner, target|
+                proc { |*a| send(target, *a, &inner) }
+              end
+              result = if calls[:around].presence
+                         around_chain.call(*args)
+                       else
+                         super(*args)
+                       end
+              calls[:after]&.each do |target|
+                target.is_a?(Symbol) ? send(target, *args) : instance_exec(*args, &target)
+              end
+              result
+            end
+          end
+        end
+      end
+      private_class_method :create_override_module
     end
   end
 end

data/lib/praxis/mapper/resources/callbacks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      module Callbacks
+        extend ::ActiveSupport::Concern
+
+        included do
+          class_attribute :before_callbacks, :after_callbacks, :around_callbacks
+          self.before_callbacks = Hash.new { |h, method| h[method] = [] }
+          self.after_callbacks = Hash.new { |h, method| h[method] = [] }
+          self.around_callbacks = Hash.new { |h, method| h[method] = [] }
+        end
+
+        module ClassMethods
+          def before(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            before_callbacks[method] << target
+          end
+
+          def after(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            after_callbacks[method] << target
+          end
+
+          def around(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            around_callbacks[method] << target
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/query_methods.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      module QueryMethods
+        extend ::ActiveSupport::Concern
+
+        # Includes some limited, but handy query methods so we can transparently
+        # use them from the resource layer, and get wrapped resources from it
+        module ClassMethods
+          def including(args)
+            QueryProxy.new(klass: self).including(args)
+          end
+
+          def all(args = {})
+            QueryProxy.new(klass: self).all(args)
+          end
+
+          def get(args)
+            QueryProxy.new(klass: self).get(args)
+          end
+
+          def get!(args)
+            QueryProxy.new(klass: self).get!(args)
+          end
+
+          def first
+            QueryProxy.new(klass: self).first
+          end
+
+          def last
+            QueryProxy.new(klass: self).last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/query_proxy.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      class QueryProxy
+        attr_reader :klass
+
+        def initialize(klass:)
+          @klass = klass
+        end
+
+        def including(includes)
+          @_includes = includes
+          self
+        end
+
+        # Can pass extra includes through :_includes
+        # TODO: We should not use the AR includes, but first pass them through the properties, cause
+        #  we need to expand based on the resource methods, not the model methods
+        def get(condition)
+          base = klass.model._add_includes(klass.model, @_includes) # includes(nil) seems to have no effect
+          record = base._get(condition)
+
+          record.nil? ? nil : klass.wrap(record)
+        end
+
+        def get!(condition)
+          resource = get(condition)
+          # TODO: passing the :id if there is one in the condition...but can be more complex...think if we want to expose more
+          raise Praxis::Mapper::ResourceNotFound.new(type: @klass, id: condition[:id]) unless resource
+
+          resource
+        end
+
+        # Retrieve all or many wrapped resources
+        # .all -> returns them all
+        # .all(name: 'foo') -> returns all that match the name
+        def all(condition = {})
+          base = klass.model._add_includes(klass.model, @_includes) # includes(nil) seems to have no effect
+          records = base._all(condition)
+
+          klass.wrap(records)
+        end
+
+        def first
+          record = klass.model._first
+          record.nil? ? nil : klass.wrap(record)
+        end
+
+        def last
+          record = klass.model._last
+          record.nil? ? nil : klass.wrap(record)
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/typed_methods.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      # Error raised when trying to call a typed method and the validation of arguments fails
+      class IncompatibleTypeForMethodArguments < ::StandardError
+        attr_reader :errors, :method
+
+        def initialize(errors:, method:, klass:)
+          @errors = errors
+          super "Error validating/coercing arguments for call to method #{method} of class #{klass}:\n#{errors}"
+        end
+      end
+
+      module TypedMethods
+        extend ::ActiveSupport::Concern
+
+        included do
+          include Praxis::Mapper::Resources::Callbacks
+
+          class << self
+            attr_reader :signatures
+
+            def _finalize!
+              if @signatures
+                # Build the around callbacks for coercing the params for the methods with types defined
+                # Also, this needs to be before, so that we hit the coercion code before any other around callback
+                const_set(:MethodSignatures, Module.new)
+                @signatures.each do |method, type|
+                  # Also add a constant pointing to the signature type inside Signatures (and substitute ! for Bang, as that's not allowed in a constant)
+                  # For class Methods, also substitute .self for Self
+                  # This helps with debugging, as we won't get anonymous struct classes, but we'll see these better names
+                  cleaned_name = method.to_s.gsub(/!/, '_bang').to_s.gsub(/^self./, 'self_')
+                  self::MethodSignatures.const_set(cleaned_name.camelize.to_sym, type)
+                  coerce_params_for method, type
+                end
+              end
+
+              super
+            end
+
+            def signature(method_name, &block)
+              method = method_name.to_sym
+              @signatures ||= {}
+              if block_given?
+                type =
+                  Class.new(Attributor::Struct) do
+                    attributes do
+                      instance_eval(&block)
+                    end
+                  end
+                @signatures[method] = type
+              else
+                @signatures[method]
+              end
+            end
+
+            # Sets up a specific around callback to a given method, where it'd pass the loaded/coerced type from the input
+            def coerce_params_for(method, type)
+              raise "Argument type for #{method} could not be found. Did you define a `signature` stanza for it?" unless type
+
+              if method.start_with?('self.')
+                simple_name = method.to_s.gsub(/^self./, '').to_sym
+                # Look for a Class method
+                raise "Error building typed method signature: Method #{method} is not defined in class #{name}" unless methods.include?(simple_name)
+
+                coerce_params_for_class(method(simple_name), type)
+              else
+                # Look for an instance method
+                raise "Error building typed method signature: Method #{method} is not defined in class #{name}" unless method_defined?(method)
+
+                coerce_params_for_instance(instance_method(method), type)
+              end
+            end
+
+            def coerce_params_for_instance(method, type)
+              around_method_name = "_coerce_params_for_#{method.name}"
+              instance_exec around_method_name: around_method_name,
+                            orig_method: method,
+                            type: type,
+                            ctx: [to_s, method.name].freeze,
+                            &CREATE_LOADER_METHOD
+
+              # Set an around callback to call the defined method above
+              around method.name, around_method_name
+            end
+
+            def coerce_params_for_class(method, type)
+              around_method_name = "_coerce_params_for_class_#{method.name}"
+              # Define an instance method in the eigenclass
+              singleton_class.instance_exec around_method_name: around_method_name,
+                                            orig_method: method,
+                                            type: type,
+                                            ctx: [to_s, method.name].freeze,
+                                            &CREATE_LOADER_METHOD
+
+              # Set an around callback to call the defined method above (the callbacks need self. for class interceptors)
+              class_method_name = "self.#{method.name}"
+              around class_method_name.to_sym, around_method_name
+            end
+
+            CREATE_LOADER_METHOD = proc do |around_method_name:, orig_method:, type:, ctx:|
+              has_args = orig_method.parameters.any? { |(argtype, _)| %i[req opt rest].include?(argtype) }
+              has_kwargs = orig_method.parameters.any? { |(argtype, _)| %i[keyreq keyrest].include?(argtype) }
+              raise "Typed signatures aren't supported for methods that have both kwargs and normal args: #{orig_method.name} of #{self.class}" if has_args && has_kwargs
+
+              if has_args
+                define_method(around_method_name) do |arg, &block|
+                  loaded = type.load(arg, ctx)
+                  errors = type.validate(loaded, ctx, nil)
+                  raise IncompatibleTypeForMethodArguments.new(errors: errors, method: orig_method.name, klass: self) unless errors.empty?
+
+                  # pass the struct object as a single arg
+                  block.yield(loaded)
+                end
+              else
+                define_method(around_method_name) do |**args, &block|
+                  loaded = type.load(args, ctx)
+                  errors = type.validate(loaded, ctx, nil)
+                  raise IncompatibleTypeForMethodArguments.new(errors: errors, method: orig_method.name, klass: self) unless errors.empty?
+
+                  # Splat the args if it's a kwarg type method
+                  block.yield(**loaded)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Praxis
-  VERSION = '2.0.pre.21'
+  VERSION = '2.0.pre.22'
 end

data/lib/praxis.rb

@@ -136,6 +136,13 @@ module Praxis
   module Mapper
     autoload :Resource, 'praxis/mapper/resource'
     autoload :SelectorGenerator, 'praxis/mapper/selector_generator'
+
+    module Resources
+      autoload :Callbacks, 'praxis/mapper/resources/callbacks'
+      autoload :QueryMethods, 'praxis/mapper/resources/query_methods'
+      autoload :TypedMethods, 'praxis/mapper/resources/typed_methods'
+      autoload :QueryProxy, 'praxis/mapper/resources/query_proxy'
+    end
   end
 
   # Avoid loading responses (and templates) lazily as they need to be registered in time

data/praxis.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables << 'praxis'
 
   spec.add_dependency 'activesupport', '>= 3'
-  spec.add_dependency 'attributor', '>= 6.0'
+  spec.add_dependency 'attributor', '>= 6.2'
   spec.add_dependency 'mime', '~> 0'
   spec.add_dependency 'mustermann', '>=1.1', '<=2'
   spec.add_dependency 'rack', '>= 1'

data/spec/praxis/mapper/resource_spec.rb

@@ -32,7 +32,9 @@ describe Praxis::Mapper::Resource do
   context 'retrieving resources' do
     context 'getting a single resource' do
       before do
-        expect(SimpleModel).to receive(:get).with(name: 'george xvi').and_return(record)
+        expect(SimpleModel).to receive(:get) do |args|
+          expect(**args).to match(name: 'george xvi')
+        end.and_return(record)
       end
 
       subject(:resource)  { SimpleResource.get(name: 'george xvi') }
@@ -44,7 +46,9 @@ describe Praxis::Mapper::Resource do
 
     context 'getting multiple resources' do
       before do
-        expect(SimpleModel).to receive(:all).with(name: ['george xvi']).and_return([record])
+        expect(SimpleModel).to receive(:all) do |args|
+          expect(**args).to eq(name: ['george xvi'])
+        end.and_return([record])
       end
 
       subject(:resource_collection) { SimpleResource.all(name: ['george xvi']) }
@@ -176,4 +180,38 @@ describe Praxis::Mapper::Resource do
       expect(SimpleResource.wrap(record)).to be(OtherResource.wrap(record))
     end
   end
+
+  context 'calling typed methods' do
+    let(:resource) { TypedResource }
+    context 'class level ones' do
+      it 'kwarg methods get their args splatted in the top level' do
+        arg = resource.create(name: 'Praxis-licious', payload: { struct_param: { id: 1 } })
+        # Top level args are a hash (cause the typed methods will splat them before calling)
+        expect(arg).to be_kind_of Hash
+        # But structs beyond that are just the loaded types (which we can splat if we want to keep calling)
+        expect(arg[:payload]).to be_kind_of Attributor::Struct
+      end
+
+      it 'non-kwarg methods get a single arg' do
+        arg = resource.singlearg_create({ name: 'Praxis-licious', payload: { struct_param: { id: 1 } } })
+        # Single argument, instance of an Attributor Struct
+        expect(arg).to be_kind_of Attributor::Struct
+      end
+    end
+    context 'instance level ones' do
+      it 'kwarg methods get their args splatted in the top level' do
+        arg = resource.new({}).update!(string_param: 'Stringer', struct_param: { id: 1 })
+        # Top level args are a hash (cause the typed methods will splat them before calling)
+        expect(arg).to be_kind_of Hash
+        # But structs beyond that are just the loaded types (which we can splat if we want to keep calling)
+        expect(arg[:struct_param]).to be_kind_of Attributor::Struct
+      end
+
+      it 'non-kwarg methods get a single arg' do
+        arg = resource.new({}).singlearg_update!({ string_param: 'Stringer', struct_param: { id: 1 } })
+        # Single argument, instance of an Attributor Struct
+        expect(arg).to be_kind_of Attributor::Struct
+      end
+    end
+  end
 end

data/spec/praxis/mapper/resources/callbacks_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Praxis::Mapper::Resources::Callbacks do
+  context 'callbacks' do
+    let(:double_model) do
+      SimpleModel.new(before_count: 0, after_count: 0, around_count: 0, name: '', force: false)
+    end
+    let(:resource) { SimpleResource.new(double_model) }
+    context 'using functions with args and kwargs' do
+      subject { resource.change_name('hi', force: true) }
+      it 'before' do
+        expect(subject.record.before_count).to eq(1) # 1 before hook
+      end
+      it 'after' do
+        expect(subject.record.after_count).to eq(1) # 1 after hook
+      end
+      it 'around' do
+        # 50, just for the only filter
+        expect(subject.record.around_count).to eq(50)
+      end
+      after do
+        # one for the before, the around filter, the actual method and the after filter
+        expect(subject.record.name).to eq('hi-hi-hi-hi')
+        expect(subject.record.force).to be_truthy
+      end
+    end
+
+    context 'using functions with only kwargs' do
+      subject { resource.update!(number: 1000) }
+      it 'before' do
+        expect(subject.record.before_count).to eq(1) # 1 before hook
+      end
+      it 'after' do
+        expect(subject.record.after_count).to eq(1) # 1 after hook
+      end
+      it 'around' do
+        # 1000 for the orig update+1 from before_count + 50+100 for the 2 around filters
+        expect(subject.record.around_count).to eq(1151)
+      end
+    end
+
+    context 'using functions only args' do
+      subject { resource.argsonly('hi') }
+      it 'around' do
+        # 50, just for the only filter
+        expect(subject.record.around_count).to eq(50)
+      end
+      after do
+        # one for the the around filter and one for the actual methodr
+        expect(subject.record.name).to eq('hi-hi')
+      end
+    end
+  end
+end

data/spec/praxis/mapper/resources/query_proxy_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Praxis::Mapper::Resources::QueryProxy do
+  let(:instance) { described_class.new(klass: resource_class) }
+  let(:resource_class) { SimpleResource }
+  let(:the_includes) { nil }
+
+  context 'including' do
+    let(:the_includes) { %i[one two] }
+    it 'saves the includes' do
+      expect(instance.instance_variable_get(:@_includes)).to be_nil
+      result = instance.including(the_includes)
+      expect(instance.instance_variable_get(:@_includes)).to be(the_includes)
+      expect(result).to be instance
+    end
+  end
+
+  context 'get' do
+    subject { instance.get(id: 39) }
+    # Base responds to the underlying ORM method _get to retrieve a record given a condition
+    let(:base) { double('ORM Base', _get: model_instance) }
+
+    before do
+      expect(resource_class.model).to receive(:_add_includes) do |model, includes|
+        expect(model).to be SimpleModel
+        expect(includes).to be(the_includes)
+      end.and_return(base)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'all' do
+    subject { instance.all(id: 39, name: 'foo') }
+    # Base responds to the underlying ORM method _all to retrieve a list of records given a condition
+    let(:base) { double('ORM Base', _all: model_instances) }
+
+    before do
+      expect(resource_class.model).to receive(:_add_includes) do |model, includes|
+        expect(model).to be SimpleModel
+        expect(includes).to be(the_includes)
+      end.and_return(base)
+    end
+    context 'when no records found' do
+      let(:model_instances) { nil }
+      it 'returns nil' do
+        expect(subject).to be_empty
+      end
+    end
+
+    context 'with found records' do
+      let(:model_instances) { [SimpleModel.new(id: 1), SimpleModel.new(id: 2)] }
+      it 'returns an array of resource instances, each wrapping their record' do
+        expect(subject).to be_kind_of(Array)
+        expect(subject.map(&:record)).to eq(model_instances)
+      end
+    end
+  end
+
+  context 'first' do
+    subject { instance.first }
+    before do
+      expect(resource_class.model).to receive(:_first).and_return(model_instance)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'last' do
+    subject { instance.last }
+    before do
+      expect(resource_class.model).to receive(:_last).and_return(model_instance)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'get!' do
+    subject { instance.get!(id: 39) }
+    before do
+      # Expects to always call the normal get function for the result
+      expect(instance).to receive(:get) do |args|
+        expect(args[:id]).to eq(39)
+      end.and_return(resource_instance)
+    end
+    context 'when no record is found' do
+      let(:resource_instance) { nil }
+      it 'raises ResourceNotFound' do
+        expect { subject }.to raise_error(Praxis::Mapper::ResourceNotFound)
+      end
+    end
+    context 'with a record found' do
+      let(:resource_instance) { double('ResourceInstance') }
+      it 'simply returns the result of get' do
+        expect(subject).to be(resource_instance)
+      end
+    end
+  end
+end

data/spec/praxis/mapper/resources/typed_methods_spec.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Praxis::Mapper::Resources::TypedMethods do
+  let(:resource_class) { TypedResource }
+
+  context '._finalize!' do
+    # The class is already finalized by loading the TypedResource from the spec_resources
+    # So we will simply check that all the right things are created
+    it 'builds the MethodSignatures constant within the class' do
+      expect(TypedResource::MethodSignatures).to_not be_nil
+    end
+
+    it 'builds the inner class type for the defined signatures' do
+      expect(TypedResource::MethodSignatures::UpdateBang).to_not be_nil
+      expect(TypedResource::MethodSignatures::UpdateBang).to be TypedResource.signature(:update!)
+
+      expect(TypedResource::MethodSignatures::SelfCreate).to_not be_nil
+      expect(TypedResource::MethodSignatures::SelfCreate).to be TypedResource.signature(:'self.create')
+    end
+
+    it 'Subsitutes a ! for a Bang when creating the constant' do
+      expect(TypedResource::MethodSignatures::UpdateBang).to be TypedResource.signature(:update!)
+    end
+
+    it 'defines the coercing methods' do
+      expect(TypedResource.methods).to include(:_coerce_params_for_class_create)
+      expect(TypedResource.instance_methods).to include(:_coerce_params_for_update!)
+    end
+  end
+
+  context '.signature' do
+    # We are not creating more classes and signatures, simply checking that the ones created
+    # for TypedResource in the spec_resource_files are correctly processed
+    it 'defines it in the @signatures hash' do
+      expect(TypedResource.signatures.keys).to match_array(
+        %i[
+          self.create
+          self.singlearg_create
+          create
+          update!
+          singlearg_update!
+        ]
+      )
+      expect(TypedResource.signature(:'self.create')).to be < Attributor::Struct
+      expect(TypedResource.signature(:create)).to be < Attributor::Struct
+      expect(TypedResource.signature(:update!)).to be < Attributor::Struct
+    end
+
+    it 'holds the right definition for class create' do
+      definition = TypedResource.signature(:'self.create')
+      expect(definition.attributes.keys).to eq %i[name payload]
+      expect(definition.attributes[:payload].attributes.keys).to eq %i[string_param struct_param]
+    end
+
+    it 'holds the right definition for instance create' do
+      definition = TypedResource.signature(:create)
+      expect(definition.attributes.keys).to eq %i[id]
+    end
+    it 'holds the right definition for update!' do
+      definition = TypedResource.signature(:update!)
+      expect(definition.attributes.keys).to eq %i[string_param struct_param]
+      expect(definition.attributes[:struct_param].attributes.keys).to eq %i[id]
+    end
+  end
+
+  context 'coerce_params_for' do
+    let(:resource_class) do
+      Class.new(Praxis::Mapper::Resource) do
+        include Praxis::Mapper::Resources::TypedMethods
+        def imethod_args(args)
+          args
+        end
+
+        def self.cmethod_args(args)
+          args
+        end
+
+        def imethod_kwargs(**args)
+          args
+        end
+
+        def self.cmethod_kwargs(**args)
+          args
+        end
+      end
+    end
+
+    let(:hook_coercer) { methods.each { |method| resource_class.coerce_params_for(method, type) } }
+    # Note, we're associating the same type signature for both imethod and cmethod signatures!
+    let(:type) do
+      Class.new(Attributor::Struct) do
+        attributes do
+          attribute :id, Integer, required: true
+          attribute :name, String, null: false
+        end
+      end
+    end
+
+    before do
+      # None of our wrappers before invoking the function
+      our_wrappers = resource_class.methods.select { |m| m.to_s =~ /^_coerce_params_for_class_/ }
+      our_wrappers +=  resource_class.instance_methods.select { |m| m.to_s =~ /^_coerce_params_for_/ }
+      expect(our_wrappers).to be_empty
+    end
+    context 'instance methods' do
+      let(:methods) { %i[imethod_args imethod_kwargs] }
+      it 'creates the wrapper methods' do
+        hook_coercer
+        iwrappers = resource_class.instance_methods.select { |m| m.to_s =~ /^_coerce_params_for_/ }
+        expect(iwrappers).to match_array %i[_coerce_params_for_imethod_args _coerce_params_for_imethod_kwargs]
+      end
+
+      it 'sets an around callback for them' do
+        hook_coercer
+        expect(resource_class.around_callbacks[:imethod_args]).to eq([:_coerce_params_for_imethod_args])
+        expect(resource_class.around_callbacks[:imethod_kwargs]).to eq([:_coerce_params_for_imethod_kwargs])
+      end
+
+      context 'when hooking in the callbacks' do
+        before do
+          hook_coercer
+          resource_class._finalize!
+        end
+        context 'calls the wrapper to validate and load' do
+          it 'fails if invalid (id is required)' do
+            expect do
+              resource_class.new(nil).imethod_args({ name: 'Praxis' })
+            end.to raise_error(
+              Praxis::Mapper::Resources::IncompatibleTypeForMethodArguments,
+              /.imethod_args.id is required/
+            )
+            expect do
+              resource_class.new(nil).imethod_kwargs(name: 'Praxis')
+            end.to raise_error(
+              Praxis::Mapper::Resources::IncompatibleTypeForMethodArguments,
+              /.imethod_kwargs.id is required/
+            )
+          end
+
+          it 'succeeds and returns the coerced struct if compatible' do
+            result = resource_class.new(nil).imethod_args({ id: '1', name: 'Praxis' })
+            expect(result[:id]).to eq(1) # Coerces to Integer!
+            expect(result[:name]).to eq('Praxis')
+            result = resource_class.new(nil).imethod_kwargs(id: '1', name: 'Praxis')
+            expect(result[:id]).to eq(1) # Coerces to Integer!
+            expect(result[:name]).to eq('Praxis')
+          end
+        end
+      end
+    end
+
+    context 'class methods' do
+      let(:methods) { %i[self.cmethod_args self.cmethod_kwargs] }
+      it 'creates the wrapper methods' do
+        hook_coercer
+        cwrappers = resource_class.methods.select { |m| m.to_s =~ /^_coerce_params_for_class_/ }
+        expect(cwrappers).to match_array %i[_coerce_params_for_class_cmethod_args _coerce_params_for_class_cmethod_kwargs]
+      end
+
+      it 'sets an around callback for them' do
+        hook_coercer
+        expect(resource_class.around_callbacks[:'self.cmethod_args']).to eq([:_coerce_params_for_class_cmethod_args])
+        expect(resource_class.around_callbacks[:'self.cmethod_kwargs']).to eq([:_coerce_params_for_class_cmethod_kwargs])
+      end
+
+      context 'when hooking in the callbacks' do
+        before do
+          hook_coercer
+          resource_class._finalize!
+        end
+        context 'calls the wrapper to validate and load' do
+          it 'fails if invalid (id is required)' do
+            expect do
+              resource_class.cmethod_args({ name: 'Praxis' })
+            end.to raise_error(
+              Praxis::Mapper::Resources::IncompatibleTypeForMethodArguments,
+              /.cmethod_args.id is required/
+            )
+            expect do
+              resource_class.cmethod_kwargs(name: 'Praxis')
+            end.to raise_error(
+              Praxis::Mapper::Resources::IncompatibleTypeForMethodArguments,
+              /.cmethod_kwargs.id is required/
+            )
+          end
+
+          it 'succeeds and returns the coerced struct if compatible' do
+            result = resource_class.cmethod_args({ id: '1', name: 'Praxis' })
+            expect(result[:id]).to eq(1) # Coerces to Integer!
+            expect(result[:name]).to eq('Praxis')
+            result = resource_class.cmethod_kwargs(id: '1', name: 'Praxis')
+            expect(result[:id]).to eq(1) # Coerces to Integer!
+            expect(result[:name]).to eq('Praxis')
+          end
+        end
+      end
+    end
+  end
+end

data/spec/support/spec_resources.rb

@@ -77,6 +77,12 @@ class YamlArrayModel < OpenStruct
   end
 end
 
+class TypedModel < OpenStruct
+  def self._praxis_associations
+    {}
+  end
+end
+
 # A set of resource classes for use in specs
 class BaseResource < Praxis::Mapper::Resource
   def href
@@ -100,6 +106,8 @@ class ParentResource < BaseResource
 end
 
 class SimpleResource < BaseResource
+  include Praxis::Mapper::Resources::Callbacks
+
   model SimpleModel
 
   resource_delegate other_model: [:other_attribute]
@@ -123,8 +131,132 @@ class SimpleResource < BaseResource
   property :no_deps, dependencies: []
 
   property :deep_nested_deps, dependencies: ['parent.simple_children.other_model.parent.display_name']
+
+  before(:update!, :do_before_update)
+  around(:update!, :do_around_update_nested)
+  around(:update!, :do_around_update)
+  # Define an after as a proc
+  after(:update!) do |number:|
+    _unused = number
+    record.after_count += 1
+  end
+
+  def do_before_update(number:)
+    _unused = number
+    record.before_count += 1
+  end
+
+  def do_around_update_nested(number:)
+    record.around_count += 100
+    yield(number: number)
+  end
+
+  def do_around_update(number:)
+    record.around_count += 50
+    yield(number: number)
+  end
+
+  around(:change_name, :do_around_change_name)
+  after(:change_name, :do_after_change_name)
+  # Define a before as a proc
+  before(:change_name) do |name, force:|
+    _unused = force
+    record.before_count += 1
+    record.name = name
+    record.force = false # Force always false in before
+  end
+
+  def do_after_change_name(name, force:)
+    _unused = force
+    record.after_count += 1
+    record.name += "-#{name}"
+  end
+
+  def do_around_change_name(name, force:)
+    record.around_count += 50
+
+    record.name += "-#{name}"
+    yield(name, force: force)
+  end
+
+  # Appends the name and overrides the force
+  def change_name(name, force:)
+    record.name += "-#{name}"
+    record.force = force
+    self
+  end
+
+  around(:argsonly, :do_around_argsonly)
+  def do_around_argsonly(name)
+    record.around_count += 50
+    record.name += name.to_s
+    yield(name)
+  end
+
+  def argsonly(name)
+    record.name += "-#{name}"
+    self
+  end
+
+  # Adds 1000 to the around count, plus whatever has been accumulated in before_count
+  def update!(number:)
+    record.around_count += number + record.before_count
+    self
+  end
 end
 
 class YamlArrayResource < BaseResource
   model YamlArrayModel
 end
+
+class TypedResource < BaseResource
+  include Praxis::Mapper::Resources::TypedMethods
+
+  model TypedModel
+
+  signature(:update!) do
+    attribute :string_param, String, null: false
+    attribute :struct_param do
+      attribute :id, Integer
+    end
+  end
+  def update!(**payload)
+    payload
+  end
+
+  signature(:singlearg_update!) do
+    attribute :string_param, String, null: false
+    attribute :struct_param do
+      attribute :id, Integer
+    end
+  end
+  def singlearg_update!(payload)
+    payload
+  end
+
+  # Instance method: create, to make sure we support both an instance and a class method signature
+  signature(:create) do
+    attribute :id, String
+  end
+  def create(id:)
+    id
+  end
+
+  signature('self.create') do
+    attribute :name, String, regexp: /Praxis/
+    attribute :payload, TypedResource.signature(:update!), required: true
+  end
+
+  def self.create(**payload)
+    payload
+  end
+
+  signature('self.singlearg_create') do
+    attribute :name, String, regexp: /Praxis/
+    attribute :payload, TypedResource.signature(:update!), required: true
+  end
+
+  def self.singlearg_create(payload)
+    payload
+  end
+end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: praxis
 version: !ruby/object:Gem::Version
-  version: 2.0.pre.21
+  version: 2.0.pre.22
 platform: ruby
 authors:
 - Josep M. Blanquer
 - Dane Jensen
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-15 00:00:00.000000000 Z
+date: 2022-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.2'
 - !ruby/object:Gem::Dependency
   name: mime
   requirement: !ruby/object:Gem::Requirement
@@ -359,7 +359,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5'
-description: 
+description:
 email:
 - blanquer@gmail.com
 - dane.jensen@gmail.com
@@ -463,6 +463,10 @@ files:
 - lib/praxis/handlers/xml_sample.rb
 - lib/praxis/mapper/active_model_compat.rb
 - lib/praxis/mapper/resource.rb
+- lib/praxis/mapper/resources/callbacks.rb
+- lib/praxis/mapper/resources/query_methods.rb
+- lib/praxis/mapper/resources/query_proxy.rb
+- lib/praxis/mapper/resources/typed_methods.rb
 - lib/praxis/mapper/selector_generator.rb
 - lib/praxis/mapper/sequel_compat.rb
 - lib/praxis/media_type.rb
@@ -543,6 +547,9 @@ files:
 - spec/praxis/file_group_spec.rb
 - spec/praxis/handlers/json_spec.rb
 - spec/praxis/mapper/resource_spec.rb
+- spec/praxis/mapper/resources/callbacks_spec.rb
+- spec/praxis/mapper/resources/query_proxy_spec.rb
+- spec/praxis/mapper/resources/typed_methods_spec.rb
 - spec/praxis/mapper/selector_generator_spec.rb
 - spec/praxis/media_type_identifier_spec.rb
 - spec/praxis/media_type_spec.rb
@@ -660,7 +667,7 @@ homepage: https://github.com/praxis/praxis
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -675,8 +682,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: Building APIs the way you want it.
 test_files: []