typed_operation 0.4.2 → 1.0.0.beta1

data/lib/generators/templates/operation.rb

@@ -4,14 +4,17 @@
 module <%= namespace_name %>
   class <%= name %> < ::ApplicationOperation
     # Replace with implementation...
-    param :required_param, String
-    param :an_optional_param, Integer, convert: true, allow_nil: true
+    positional_param :required_positional_param, String
+    param :required_named_param, String
+    param :an_optional_param, Integer, optional: true do |value|
+     value.to_i
+    end
 
     def prepare
       # Prepare...
     end
 
-    def call
+    def perform
       # Perform...
       "Hello World!"
     end
@@ -20,14 +23,17 @@ end
 <% else %>
 class <%= name %> < ::ApplicationOperation
   # Replace with implementation...
-  param :required_param, String
-  param :an_optional_param, Integer, convert: true, allow_nil: true
+  positional_param :required_positional_param, String
+  param :required_named_param, String
+  param :an_optional_param, Integer, optional: true do |value|
+    value.to_i
+  end
 
   def prepare
     # Prepare...
   end
 
-  def call
+  def perform
     # Perform...
     "Hello World!"
   end

data/lib/typed_operation/action_policy_auth.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "action_policy"
+
+# An optional module to include in your operation to enable authorization via ActionPolicies
+module TypedOperation
+  class MissingAuthentication < StandardError; end
+
+  module ActionPolicyAuth
+    # Base class for any action policy classes used by operations
+    class OperationPolicy
+      include ActionPolicy::Policy::Core
+      include ActionPolicy::Policy::Authorization
+      include ActionPolicy::Policy::PreCheck
+      include ActionPolicy::Policy::Reasons
+      include ActionPolicy::Policy::Aliases
+      include ActionPolicy::Policy::Scoping
+      include ActionPolicy::Policy::Cache
+      include ActionPolicy::Policy::CachedApply
+    end
+
+    def self.included(base)
+      base.include ::ActionPolicy::Behaviour
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Configure the operation to use ActionPolicy for authorization
+      def authorized_via(*via, with: nil, to: nil, record: nil, &auth_block)
+        # If a block is provided, you must not provide a policy class or method
+        raise ArgumentError, "You must not provide a policy class or method when using a block" if auth_block && (with || to)
+
+        parameters = positional_parameters + keyword_parameters
+        raise ArgumentError, "authorize_via must be called with a valid param name" unless via.all? { |param| parameters.include?(param) }
+        @_authorized_via_param = via
+
+        action_type_method = "#{action_type}?".to_sym if action_type
+        # If an method name is provided, use it
+        policy_method = to || action_type_method || raise(::TypedOperation::InvalidOperationError, "You must provide an action type or policy method name")
+        @_policy_method = policy_method
+        # If a policy class is provided, use it
+        @_policy_class = if with
+          with
+        elsif auth_block
+          policy_class = Class.new(OperationPolicy) do
+            authorize(*via)
+
+            define_method(policy_method, &auth_block)
+          end
+          const_set(:Policy, policy_class)
+          policy_class
+        else
+          raise ::TypedOperation::InvalidOperationError, "You must provide either a policy class or a block"
+        end
+
+        if record
+          unless parameters.include?(record) || method_defined?(record) || private_instance_methods.include?(record)
+            raise ArgumentError, "to_authorize must be called with a valid param or method name"
+          end
+          @_to_authorize_param = record
+        end
+
+        # Configure action policy to use the param named in via as the context when instantiating the policy
+        # ::ActionPolicy::Behaviour does not provide a authorize(*ids) method, so we have call once per param
+        via.each do |param|
+          authorize param
+        end
+      end
+
+      def action_type(type = nil)
+        @_action_type = type.to_sym if type
+        @_action_type
+      end
+
+      def operation_policy_method
+        @_policy_method
+      end
+
+      def operation_policy_class
+        @_policy_class
+      end
+
+      def operation_record_to_authorize
+        @_to_authorize_param
+      end
+
+      def checks_authorization?
+        !(@_authorized_via_param.nil? || @_authorized_via_param.empty?)
+      end
+
+      # You can use this on an operation base class to ensure and subclasses always enable authorization
+      def verify_authorized!
+        return if verify_authorized?
+        @_verify_authorized = true
+      end
+
+      def verify_authorized?
+        @_verify_authorized
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_authorized_via_param, @_authorized_via_param)
+        subclass.instance_variable_set(:@_verify_authorized, @_verify_authorized)
+        subclass.instance_variable_set(:@_policy_class, @_policy_class)
+        subclass.instance_variable_set(:@_policy_method, @_policy_method)
+        subclass.instance_variable_set(:@_action_type, @_action_type)
+      end
+    end
+
+    private
+
+    # Redefine it as private
+    def execute_operation
+      if self.class.verify_authorized? && !self.class.checks_authorization?
+        raise ::TypedOperation::MissingAuthentication, "Operation #{self.class.name} must authorize. Remember to use `.authorize_via`"
+      end
+      operation_check_authorized! if self.class.checks_authorization?
+      super
+    end
+
+    def operation_check_authorized!
+      policy = self.class.operation_policy_class
+      raise "No Action Policy policy class provided, or no #{self.class.name}::Policy found for this action" unless policy
+      policy_method = self.class.operation_policy_method
+      raise "No policy method provided or action_type not set for #{self.class.name}" unless policy_method
+      # Record to authorize, if nil then action policy tries to work it out implicitly
+      record_to_authorize = send(self.class.operation_record_to_authorize) if self.class.operation_record_to_authorize
+
+      authorize! record_to_authorize, to: policy_method, with: policy
+    rescue ::ActionPolicy::Unauthorized => e
+      on_authorization_failure(e)
+      raise e
+    end
+
+    # A hook for subclasses to override to do something on an authorization failure
+    def on_authorization_failure(authorization_error)
+      # noop
+    end
+  end
+end

data/lib/typed_operation/base.rb

@@ -1,58 +1,25 @@
 # frozen_string_literal: true
 
-require "vident/typed"
-require "vident/typed/attributes"
-
 module TypedOperation
-  class Base
-    include Vident::Typed::Attributes
-
-    class << self
-      def call(...)
-        new(...).call
-      end
-
-      def curry(**args)
-        PartiallyApplied.new(self, **args).curry
-      end
-      alias_method :[], :curry
-      alias_method :with, :curry
-
-      def to_proc
-        method(:call).to_proc
-      end
-
-      def operation_key
-        name.underscore.to_sym
-      end
+  class Base < Literal::Struct
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
 
-      # property are required by default, you can fall back to attribute or set allow_nil: true if you want optional
-      def param(name, signature = :any, **options, &converter)
-        attribute(name, signature, **{allow_nil: false}.merge(options), &converter)
-      end
-    end
+    include Operations::Lifecycle
+    include Operations::Callable
+    include Operations::Deconstruct
+    include Operations::Executable
 
-    def initialize(**attributes)
-      begin
-        prepare_attributes(attributes)
-      rescue ::Dry::Struct::Error => e
-        raise ParameterError, e.message
+    class << self
+      def attribute(name, type, special = nil, reader: :public, writer: :public, positional: false, default: nil)
+        super(name, type, special, reader:, writer: false, positional:, default:)
       end
-      prepare if respond_to?(:prepare)
     end
 
-    def call
-      raise InvalidOperationError, "You must implement #call"
-    end
-
-    def to_proc
-      method(:call).to_proc
-    end
-
-    private
-
-    def operation_key
-      self.class.operation_key
+    def with(...)
+      # copy to new operation with new attrs
+      self.class.new(**attributes.merge(...))
     end
   end
 end

data/lib/typed_operation/curried.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class Curried
+    def initialize(operation_class, partial_operation = nil)
+      @operation_class = operation_class
+      @partial_operation = partial_operation || operation_class.with
+    end
+
+    def call(arg)
+      raise ArgumentError, "A prepared operation should not be curried" if @partial_operation.prepared?
+
+      next_partially_applied = if next_parameter_positional?
+        @partial_operation.with(arg)
+      else
+        @partial_operation.with(next_keyword_parameter => arg)
+      end
+      if next_partially_applied.prepared?
+        next_partially_applied.call
+      else
+        Curried.new(@operation_class, next_partially_applied)
+      end
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    private
+
+    def next_keyword_parameter
+      remaining = @operation_class.required_keyword_parameters - @partial_operation.keyword_args.keys
+      remaining.first
+    end
+
+    def next_parameter_positional?
+      @partial_operation.positional_args.size < @operation_class.required_positional_parameters.size
+    end
+  end
+end

data/lib/typed_operation/immutable_base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class ImmutableBase < Literal::Data
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
+
+    include Operations::Lifecycle
+    include Operations::Callable
+    include Operations::Deconstruct
+    include Operations::Executable
+  end
+end

data/lib/typed_operation/operations/attribute_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    class AttributeBuilder
+      def initialize(typed_operation, parameter_name, type_signature, options)
+        @typed_operation = typed_operation
+        @name = parameter_name
+        @signature = type_signature
+        @optional = options[:optional]
+        @positional = options[:positional]
+        @reader = options[:reader] || :public
+        @default_key = options.key?(:default)
+        @default = options[:default]
+
+        prepare_type_signature_for_literal
+      end
+
+      def define(&converter)
+        # If nilable, then converter should not attempt to call the type converter block if the value is nil
+        coerce_by = if type_nilable? && converter
+          ->(v) { (v == Literal::Null || v.nil?) ? v : converter.call(v) }
+        else
+          converter
+        end
+        @typed_operation.attribute(
+          @name,
+          @signature,
+          default: default_value_for_literal,
+          positional: @positional,
+          reader: @reader,
+          &coerce_by
+        )
+      end
+
+      private
+
+      def prepare_type_signature_for_literal
+        @signature = Literal::Types::NilableType.new(@signature) if needs_to_be_nilable?
+        union_with_nil_to_support_nil_default
+        validate_positional_order_params! if @positional
+      end
+
+      # If already wrapped in a Nilable then don't wrap again
+      def needs_to_be_nilable?
+        @optional && !type_nilable?
+      end
+
+      def type_nilable?
+        @signature.is_a?(Literal::Types::NilableType)
+      end
+
+      def union_with_nil_to_support_nil_default
+        @signature = Literal::Union.new(@signature, NilClass) if has_default_value_nil?
+      end
+
+      def has_default_value_nil?
+        default_provided? && @default.nil?
+      end
+
+      def validate_positional_order_params!
+        # Optional ones can always be added after required ones, or before any others, but required ones must be first
+        unless type_nilable? || @typed_operation.optional_positional_parameters.empty?
+          raise ParameterError, "Cannot define required positional parameter '#{@name}' after optional positional parameters"
+        end
+      end
+
+      def default_provided?
+        @default_key
+      end
+
+      def default_value_for_literal
+        if has_default_value_nil? || type_nilable?
+          -> {}
+        else
+          @default
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/callable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Callable
+      def self.included(base)
+        base.extend(CallableMethods)
+      end
+
+      module CallableMethods
+        def call(...)
+          new(...).call
+        end
+
+        def to_proc
+          method(:call).to_proc
+        end
+      end
+
+      include CallableMethods
+    end
+  end
+end

data/lib/typed_operation/operations/deconstruct.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Deconstruct
+      def deconstruct
+        attributes.values
+      end
+
+      def deconstruct_keys(keys)
+        h = attributes.to_h
+        keys ? h.slice(*keys) : h
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/executable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Executable
+      def call
+        execute_operation
+      end
+
+      def execute_operation
+        before_execute_operation
+        retval = perform
+        after_execute_operation(retval)
+      end
+
+      def before_execute_operation
+        # noop
+      end
+
+      def after_execute_operation(retval)
+        retval
+      end
+
+      def perform
+        raise InvalidOperationError, "Operation #{self.class} does not implement #perform"
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/introspection.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Introspection methods
+    module Introspection
+      def positional_parameters
+        literal_attributes.filter_map { |name, attribute| name if attribute.positional? }
+      end
+
+      def keyword_parameters
+        literal_attributes.filter_map { |name, attribute| name unless attribute.positional? }
+      end
+
+      def required_parameters
+        literal_attributes.filter do |name, attribute|
+          attribute.default.nil? # Any optional parameters will have a default value/proc in their Literal::Attribute
+        end
+      end
+
+      def required_positional_parameters
+        required_parameters.filter_map { |name, attribute| name if attribute.positional? }
+      end
+
+      def required_keyword_parameters
+        required_parameters.filter_map { |name, attribute| name unless attribute.positional? }
+      end
+
+      def optional_positional_parameters
+        positional_parameters - required_positional_parameters
+      end
+
+      def optional_keyword_parameters
+        keyword_parameters - required_keyword_parameters
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/lifecycle.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Lifecycle
+      # This is called by Literal on initialization of underlying Struct/Data
+      def after_initialization
+        prepare if respond_to?(:prepare)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/parameters.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Method to define parameters for your operation.
+    module Parameters
+      # Parameter for keyword argument, or a positional argument if you use positional: true
+      # Required, but you can set a default or use optional: true if you want optional
+      def param(name, signature = :any, **options, &converter)
+        AttributeBuilder.new(self, name, signature, options).define(&converter)
+      end
+
+      # Alternative DSL
+
+      # Parameter for positional argument
+      def positional_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: true), &converter)
+      end
+
+      # Parameter for a keyword or named argument
+      def named_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: false), &converter)
+      end
+
+      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation
+      def optional(type_signature)
+        Literal::Types::NilableType.new(type_signature)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/partial_application.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module PartialApplication
+      def with(...)
+        PartiallyApplied.new(self, ...).with
+      end
+      alias_method :[], :with
+
+      def curry
+        Curried.new(self)
+      end
+    end
+  end
+end

data/lib/typed_operation/partially_applied.rb

@@ -2,34 +2,87 @@
 
 module TypedOperation
   class PartiallyApplied
-    def initialize(operation, **applied_args)
-      @operation = operation
-      @applied_args = applied_args
+    def initialize(operation_class, *positional_args, **keyword_args)
+      @operation_class = operation_class
+      @positional_args = positional_args
+      @keyword_args = keyword_args
     end
 
-    def curry(**params)
-      all_args = @applied_args.merge(params)
-      # check if required attrs are in @applied_args
-      required_keys = @operation.attribute_names.select do |name|
-        meta = @operation.attribute_metadata(name)
-        meta[:required] != false && !meta[:typed_attribute_options].key?(:default)
-      end
-      missing_keys = required_keys - all_args.keys
+    def with(*positional, **keyword)
+      all_positional = positional_args + positional
+      all_kw_args = keyword_args.merge(keyword)
+
+      validate_positional_arg_count!(all_positional.size)
 
-      if missing_keys.size > 0
-        # Partially apply the arguments
-        PartiallyApplied.new(@operation, **all_args)
+      if partially_applied?(all_positional, all_kw_args)
+        PartiallyApplied.new(operation_class, *all_positional, **all_kw_args)
       else
-        Prepared.new(@operation, **all_args)
+        Prepared.new(operation_class, *all_positional, **all_kw_args)
       end
     end
-    alias_method :[], :curry
-    alias_method :with, :curry
+    alias_method :[], :with
+
+    def curry
+      Curried.new(operation_class, self)
+    end
 
     def call(...)
-      prepared = curry(...)
+      prepared = with(...)
       return prepared.operation.call if prepared.is_a?(Prepared)
-      raise TypedOperation::MissingParameterError, "Cannot call PartiallyApplied operation #{@operation.name} (key: #{@operation.operation_key}), are you expecting it to be Prepared?"
+      raise MissingParameterError, "Cannot call PartiallyApplied operation #{operation_class.name} (key: #{operation_class.name}), are you expecting it to be Prepared?"
+    end
+
+    def operation
+      raise MissingParameterError, "Cannot instantiate Operation #{operation_class.name} (key: #{operation_class.name}), as it is only partially applied."
+    end
+
+    def prepared?
+      false
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    def deconstruct
+      positional_args + keyword_args.values
+    end
+
+    def deconstruct_keys(keys)
+      h = keyword_args.dup
+      positional_args.each_with_index { |v, i| h[positional_parameters[i]] = v }
+      keys ? h.slice(*keys) : h
+    end
+
+    attr_reader :positional_args, :keyword_args
+
+    private
+
+    attr_reader :operation_class
+
+    def required_positional_parameters
+      @required_positional_parameters ||= operation_class.required_positional_parameters
+    end
+
+    def required_keyword_parameters
+      @required_keyword_parameters ||= operation_class.required_keyword_parameters
+    end
+
+    def positional_parameters
+      @positional_parameters ||= operation_class.positional_parameters
+    end
+
+    def validate_positional_arg_count!(count)
+      if count > positional_parameters.size
+        raise ArgumentError, "Too many positional arguments provided for #{operation_class.name} (key: #{operation_class.name})"
+      end
+    end
+
+    def partially_applied?(all_positional, all_kw_args)
+      missing_positional = required_positional_parameters.size - all_positional.size
+      missing_keys = required_keyword_parameters - all_kw_args.keys
+
+      missing_positional > 0 || missing_keys.size > 0
     end
   end
 end

data/lib/typed_operation/prepared.rb

@@ -3,7 +3,11 @@
 module TypedOperation
   class Prepared < PartiallyApplied
     def operation
-      @operation.new(**@applied_args)
+      operation_class.new(*@positional_args, **@keyword_args)
+    end
+
+    def prepared?
+      true
     end
   end
 end