hyrax 3.0.0.pre.rc1 → 3.0.0.pre.rc2

data/lib/hyrax/transactions/destroy_work.rb

@@ -12,6 +12,10 @@ module Hyrax
     # @since 3.0.0
     #
     # @see https://dry-rb.org/gems/dry-transaction/
+    #
+    # @deprecated Development on Dry::Transaction has been discontinued, we're
+    #   removing existing transactions and replacing them with Dry::Monad-based
+    #   valkyrie versions.
     class DestroyWork
       include Dry::Transaction(container: Hyrax::Transactions::Container)
 

data/lib/hyrax/transactions/steps/add_to_collections.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+require 'dry/monads'
+
+module Hyrax
+  module Transactions
+    module Steps
+      ##
+      # Add a resource to collections via `ChangeSet`.
+      #
+      # Accepts `:collection_ids` and never retrieves the actual collections
+      # from the persisted data. We trust that the identifiers passed refer to
+      # actual, extant collections, and that the permissions to add to
+      # collection membership have been established, or else that they'll be
+      # validated prior to save.
+      #
+      # @since 3.0.0
+      class AddToCollections
+        include Dry::Monads[:result]
+
+        ##
+        # Add to collections by inserting collections to
+        # `ChangeSet#member_of_collection_ids`.
+        #
+        # @param [Hyrax::ChangeSet] change_set
+        # @param [Array<#to_s>] collection_ids
+        #
+        # @return [Dry::Monads::Result]
+        def call(change_set, collection_ids: [])
+          change_set.member_of_collection_ids += collection_ids
+
+          Success(change_set)
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/transactions/steps/apply_visibility.rb

@@ -20,12 +20,12 @@ module Hyrax
         # @return [Dry::Monads::Result] `Failure` if there is no
         #   `PermissionTemplate` for the input; `Success(input)`, otherwise.
         def call(work, visibility: nil, release_date: nil, during: nil, after: nil)
-          return Success(work) unless visibility.present?
+          return Success(work) if visibility.blank?
 
-          intention = Hyrax::VisibilityIntention.new(visibility:   visibility,
+          intention = Hyrax::VisibilityIntention.new(visibility: visibility,
                                                      release_date: release_date,
-                                                     during:       during,
-                                                     after:        after)
+                                                     during: during,
+                                                     after: after)
 
           Hyrax::VisibilityIntentionApplicator.apply(intention).to(model: work)
 

data/lib/hyrax/transactions/steps/ensure_admin_set.rb

@@ -3,19 +3,19 @@ module Hyrax
   module Transactions
     module Steps
       ##
-      # A `dry-transaction` step that ensures the input `work` has an AdminSet.
+      # A step that ensures the input object has an `#admin_set_id`.
       #
       # @since 2.4.0
       class EnsureAdminSet
-        include Dry::Transaction::Operation
+        include Dry::Monads[:result]
 
         ##
-        # @param [Hyrax::WorkBehavior] work
+        # @param [#admin_set_id] obj
         #
         # @return [Dry::Monads::Result] `Failure` if there is no `AdminSet` for
         #   the input; `Success(input)`, otherwise.
-        def call(work)
-          work.admin_set_id ? Success(work) : Failure(:no_admin_set_id)
+        def call(obj)
+          obj.admin_set_id ? Success(obj) : Failure(:no_admin_set_id)
         end
       end
     end

data/lib/hyrax/transactions/steps/save.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+require 'dry/monads'
+
+module Hyrax
+  module Transactions
+    module Steps
+      ##
+      # Saves a given work from a change_set, returning a `Dry::Monads::Result`
+      # (`Success`|`Failure`).
+      #
+      # If the save is successful, publishes an `object.metadata.updated` event
+      # for the affected resource.
+      #
+      # @see https://dry-rb.org/gems/dry-monads/1.0/result/
+      class Save
+        include Dry::Monads[:result]
+
+        ##
+        # @params [#save] persister
+        def initialize(persister: Hyrax.persister)
+          @persister = persister
+        end
+
+        ##
+        # @param [Hyrax::ChangeSet] change_set
+        # @param [::User, nil] user
+        #
+        # @return [Dry::Monads::Result] `Success(work)` if the change_set is
+        #   applied and the resource is saved;
+        #   `Failure([#to_s, change_set.resource])`, otherwise.
+        def call(change_set, user: nil)
+          saved = @persister.save(resource: change_set.sync)
+
+          Hyrax.publisher.publish('object.metadata.updated',
+                                  object: saved,
+                                  user: user)
+
+          Success(saved)
+        rescue StandardError => err
+          Failure([err.message, change_set.resource])
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/transactions/steps/set_default_admin_set.rb

@@ -3,21 +3,22 @@ module Hyrax
   module Transactions
     module Steps
       ##
-      # A `dry-transaction` step that sets the `AdminSet` for an input work to
-      # the default admin set, if none is already set. Creates the default
-      # admin set if it doesn't already exist.
+      # A step that sets the `AdminSet` for an input work to the default admin
+      # set if none is already set. Creates the default admin set if it doesn't
+      # already exist.
+      #
+      # @since 2.4.0
       class SetDefaultAdminSet
-        include Dry::Transaction::Operation
+        include Dry::Monads[:result]
 
         ##
-        # @param [Hyrax::WorkBehavior] work
+        # @param [#admin_set_id=] obj
         #
         # @return [Dry::Monads::Result]
-        def call(work)
-          work.admin_set ||=
-            AdminSet.find(AdminSet.find_or_create_default_admin_set_id)
+        def call(obj)
+          obj.admin_set_id ||= AdminSet.find_or_create_default_admin_set_id
 
-          Success(work)
+          Success(obj)
         end
       end
     end

data/lib/hyrax/transactions/steps/set_modified_date.rb

@@ -3,21 +3,30 @@ module Hyrax
   module Transactions
     module Steps
       ##
-      # A `dry-transaction` step that sets the modified date to now for an
-      # input work.
+      # A step that sets the modified date to now for an input resource or
+      # change_set
       #
       # @since 2.4.0
       class SetModifiedDate
-        include Dry::Transaction::Operation
+        include Dry::Monads[:result]
 
         ##
-        # @param [Hyrax::WorkBehavior] work
+        # @param [#time_in_utc] time_service
+        def initialize(time_service: Hyrax::TimeService)
+          @time_service = time_service
+        end
+
+        ##
+        # @param [#date_modified=] obj
         #
         # @return [Dry::Monads::Result]
-        def call(work)
-          work.date_modified = Hyrax::TimeService.time_in_utc
+        def call(obj)
+          return Failure[:no_date_modified_attribute, obj] unless
+            obj.respond_to?(:date_modified=)
+
+          obj.date_modified = @time_service.time_in_utc
 
-          Success(work)
+          Success(obj)
         end
       end
     end

data/lib/hyrax/transactions/steps/set_uploaded_date_unless_present.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+module Hyrax
+  module Transactions
+    module Steps
+      ##
+      # A step that sets the uploaded date for an input `Valkyrie::Resource` or
+      # `ValkyrieChangeSet`.
+      #
+      # The uploaded date is derived in the following way:
+      #
+      #   - if a `date_uploaded` is already present, keep it;
+      #   - if there is no current `date_uploaded` but `date_modified` is
+      #     present, use the value of `date_modified`.
+      #   - if neither `date_uploaded` nor `date_modified` is present, set the
+      #     time to now using the given `time_service`. `Hyrax::TimeService`
+      #     is used by default.
+      #
+      # A useful pattern is to run this step immediately following one to set
+      # the `date_modified` to now, and just before validation and save. This
+      # pattern ensures the times for a newly created object have the same
+      # value as close to the actual save time as practicable, and avoids
+      # overwriting `date_uploaded` for existing objects.
+      #
+      # @since 3.0.0
+      class SetUploadedDateUnlessPresent
+        include Dry::Monads[:result]
+
+        ##
+        # @param [#time_in_utc] time_service
+        def initialize(time_service: Hyrax::TimeService)
+          @time_service = time_service
+        end
+
+        ##
+        # @note the implementation sets the uploaded date to
+        #   `#date_modified` if it exists, falling back on the current datetime.
+        #
+        # @param [#date_uploaded=] obj
+        #
+        # @return [Dry::Monads::Result]
+        def call(obj)
+          return Failure[:no_date_uploaded_attribute, obj] unless
+            obj.respond_to?(:date_uploaded=)
+
+          obj.date_uploaded = date_uploaded(obj) if obj.date_uploaded.blank?
+
+          Success(obj)
+        end
+
+        private
+
+        def date_uploaded(obj)
+          obj.try(:date_modified).presence || @time_service.time_in_utc
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/transactions/steps/set_user_as_depositor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require 'dry/monads'
+
+module Hyrax
+  module Transactions
+    module Steps
+      ##
+      # Add a given `::User` as the `#depositor` via a ChangeSet.
+      #
+      # If no user is given, simply passes as a `Success`.
+      #
+      # @since 3.0.0
+      class SetUserAsDepositor
+        include Dry::Monads[:result]
+
+        ##
+        # @param [Hyrax::ChangeSet] change_set
+        # @param [#user_key] user
+        #
+        # @return [Dry::Monads::Result]
+        def call(change_set, user: NullUser.new)
+          change_set.depositor = user.user_key if user.user_key
+
+          Success(change_set)
+        rescue NoMethodError => err
+          Failure([err.message, change_set])
+        end
+
+        ##
+        # @api private
+        class NullUser
+          ##
+          # @return [nil]
+          def user_key
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/transactions/steps/validate.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+require 'dry/monads'
+
+module Hyrax
+  module Transactions
+    module Steps
+      ##
+      # Validates a ChangeSet, returning `Success(change_set)` if valid, and
+      # a `Failure` including the errors otherwise.
+      #
+      # Callers provide the particular `ChangeSet` to validate, and its validity
+      # status is delegated by its own configuration/implementation.
+      #
+      # It is good practice to run this validation as a precursor to any step
+      # that will sync a ChangeSet or save its resource. A `Failure` return
+      # value in the context of a transaction will prevent the sync/save step
+      # from running.
+      #
+      # @since 3.0.0
+      class Validate
+        include Dry::Monads[:result]
+
+        ##
+        # @param [Hyrax::ChangeSet] change_set
+        #
+        # @return [Dry::Monads::Result] `Success(input)` if the change_set is valid;
+        #   `Failure`, otherwise.
+        def call(change_set)
+          return Success(change_set) if change_set.valid?
+
+          Failure([:failed_validation, change_set.errors])
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/transactions/transaction.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'dry/monads'
+require 'dry/monads/do'
+
+module Hyrax
+  module Transactions
+    ##
+    # Queues up a set of `#steps` to run over a value via `#call`. Steps are
+    # given by name, and resolved at runtime via `container`, which defaults to
+    # `Hyrax::Transactions::Container`. This allows injection of specific
+    # handling for named steps at any time.
+    #
+    # `#call` will **ALWAYS** return a `Result` (`Success`|`Failure`) and it's
+    # recommended for users to handle the output in a way that directly
+    # addresses the `Failure` case. The simplest way to do this is to use
+    # `#value_or`: `tx.call(my_value).value_or { |failure| handle_failure(f) }`.
+    #
+    # @since 3.0.0
+    #
+    # @example running a transaction for a set of steps
+    #   steps = ['change_set.validate', 'change_set.save']
+    #   tx    = Hyrax::Transactions::Transaction.new(steps: steps)
+    #
+    #   change_set = Hyrax::ChangeSet.for(Hyrax::Work.new)
+    #   change_set.title = ['comet in moominland']
+    #
+    #   tx.call(change_set) # => Success(#<Hyrax::Work ...>)
+    #
+    # @example with a failure
+    #   class ChangeSetWithTitleValidation < Hyrax::ChangeSet
+    #     self.fields = [:title]
+    #     validates :title, presence: true
+    #   end
+    #
+    #   change_set = ChangeSetWithTitleValidation.new(Hyrax::Work.new)
+    #   change_set.title = []
+    #
+    #   tx.call(change_set)
+    #   # => Failure([:failed_validation, #<Reform::Form::ActiveModel::Errors ...>]
+    #
+    # @example unwapping values safely with handling for failures
+    #   tx.call(change_set).value_or { |failure| "uh oh: #{failure} }
+    #
+    # @example when there is no need to unwrap the value, handle errors with `#or`
+    #   tx.call(change_set).or { |failure| "uh oh: #{failure} }
+    #
+    # @example a pattern for subclassing to create new transactions
+    #   class CustomTransaction < Transaction
+    #     DEFAULT_STEPS = ['step.1', 'step.2', 'step.3'].freeze
+    #
+    #     def initialize(container: Container, steps: DEFAULT_STEPS)
+    #       super
+    #     end
+    #   end
+    #
+    #   tx = CustomTransaction.new
+    #   tx.call(:some_value)
+    #
+    class Transaction
+      include Dry::Monads[:result]
+      include Dry::Monads::Do.for(:call)
+
+      ##
+      # @!attribute [rw] container
+      #   @return [Container]
+      # @!attribute [rw] steps
+      #   @return [Array<String>]
+      attr_accessor :container, :steps
+
+      ##
+      # @api public
+      #
+      # @param [Container] container
+      # @param [Array<String>] steps
+      def initialize(container: Container, steps:)
+        self.container = container
+        self.steps     = steps
+      end
+
+      ##
+      # @api public
+      #
+      # Run each step name in `#steps` by resolving the name in the given
+      # `container` and passing a value to call. Each step must return a
+      # `Result`. In the event of a `Success`, the wrapped value is passed
+      # through to the next step; for `Failure` the whole chain is short-
+      # circuited and the failure result is given.
+      #
+      # @param [Object] value
+      #
+      # @return [Dry::Monads::Result] either the `Success` result of the entire
+      #   `#steps` chain over `value`, or a `Failure` from the failed step.
+      # @see Dry::Monads::Do
+      def call(value)
+        Success(
+          steps.inject(value) do |val, step_name|
+            yield container[step_name].call(val, *step_arguments_for(step_name))
+          end
+        )
+      end
+
+      ##
+      # Sets arguments to pass to a given step in the transaction.
+      #
+      # This makes it easy for individual steps to require pieces of information
+      # without other steps having to handle them. This is desirable since it
+      # avoids passing mutable values between steps, which commonly results in
+      # tight interdependence and less flexible composibility between steps.
+      #
+      # Instead we expect the caller to provide the correct data to each step
+      # when the transaction starts.
+      #
+      # @param [Hash<Object, Array>] args
+      #
+      # @return [Transaction] returns self
+      #
+      # @example passing arguments for a named step
+      #   tx = Hyrax::Transactions::Transaction.new(steps: [:first_step, :second_step])
+      #   result = tx.with_step_args(second_step: {named_parameter: :param_value}).call(:value)
+      #
+      def with_step_args(args)
+        raise(ArgumentError, key_err_msg(args.keys)) if
+          args.keys.any? { |key| !step?(key) }
+
+        @_step_args = args
+        self
+      end
+
+      private
+
+      ##
+      # @api private
+      # @param [String, Symbol] step_name
+      # @return [Array]
+      def step_arguments_for(step_name)
+        step_args = @_step_args || {}
+
+        Array.wrap(step_args[step_name])
+      end
+
+      ##
+      # @api private
+      # @param [Array] keys
+      # @return [String]
+      def key_err_msg(keys)
+        missing_steps = keys.select { |key| !step?(key) }
+
+        "Tried to pass step arguments for unknown steps #{missing_steps.join(', ')}\n" \
+        "\tSteps defined for this transaction are: #{@steps.join(', ')}"
+      end
+
+      ##
+      # @api private
+      # @param [String, Symbol] step_name
+      def step?(step_name)
+        steps.include?(step_name)
+      end
+    end
+  end
+end