session.rb in eco-helpers-1.5.2

- old
+ new

@@ -15,21 +15,17 @@
         @person_factories = {}
 
         logger.debug("LINE COMMAND: #{$0} #{ARGV.join(" ")}")
       end
 
-      # Helper to perform multiple operations in one go.
-      # @return [Eco::API::Session::Task] provides shortcuts to manage certain kind of operations.
-      def do
-        @task   ||= Task.new(enviro)
-      end
-
       # @return [Eco::API::Session::Batch] provides helper to launch batch operations.
       def batch
         @batch  ||= Batch.new(enviro)
       end
 
+      # @!group Pure organization helpers
+
       # @see Eco::API::Session::Config#policy_groups
       def policy_groups
         config.policy_groups
       end
 
@@ -45,28 +41,31 @@
 
       # @see Eco::API::Session::Config#schemas
       def schemas
         config.schemas
       end
+      # @!endgroup
 
+      # @!group People and Input entries helpers
+
       # @return [String, Ecoportal::API::V1::PersonSchema] current active session's schema
       def schema
         self.schema = config.people.default_schema || schemas.first unless @schema
         @schema
       end
 
       # Sets the current target `PersonSchema` of this session.
       # @note observe that it is essential for the parsers/serialisers to identify target/present attributes.
-      # @param schema [String, Ecoportal::API::V1::PersonSchema] where `String` can be the _name_ or the _id_ of the schema.
+      # @param value [String, Ecoportal::API::V1::PersonSchema] where `String` can be the _name_ or the _id_ of the schema.
       def schema=(value)
         @schema = to_schema(value)
         self
       end
 
       # Builds the presets using the usergroup ids of the input.
       # @note for each flag/ability it will take the highest among those mapped for the present usergroups.
-      # @param [Ecoportal::API::Internal::Person, Array<String>] the array should be of usegroup names or ids.
+      # @param input [Ecoportal::API::Internal::Person, Array<String>] the array should be of usegroup names or ids.
       # @return [Hash] with custom presets.
       def new_preset(input)
         case input
         when Ecoportal::API::Internal::Person
           presets_factory.new(*input&.account&.policy_group_ids)
@@ -75,10 +74,19 @@
         else
           presets_factory.new(input)
         end
       end
 
+      # Helper to state the abilities that a person should have with given their usergroups
+      def presets_factory
+        @presets_factory ||= Eco::API::Organization::PresetsFactory.new({
+          presets_custom: file_manager.dir.file(config.people.presets_custom, should_exist: true),
+          presets_map:    file_manager.dir.file(config.people.presets_map,    should_exist: true),
+          enviro:         enviro
+        })
+      end
+
       # Helper to obtain a EntryFactory
       # @param schema [String, Ecoportal::API::V1::PersonSchema] `schema` to which associate the EntryFactory,
       #  where `String` can be the _name_ or the _id_ of the schema.
       # @return [Eco::API::Common::People::EntryFactory] associated to `schema`.
       #  If `schema` is `nil` or not provided it uses the currently associated to the `session`
@@ -101,32 +109,36 @@
 
       # Helper to obtain a  PersonFactory
       # @param schema [String, Ecoportal::API::V1::PersonSchema] `schema` to which associate the PersonFactory,
       #  where `String` can be the _name_ or the _id_ of the schema.
       # @return [Eco::API::Common::People::PersonFactory] associated to `schema`.
-      #  If `schema` is `nil` or not provided it uses the currently associated to the `session`
+      #   If `schema` is `nil` or not provided it uses the currently associated to the `session`
       def person_factory(schema: nil)
         schema = to_schema(schema) || self.schema
         @person_factories[schema&.id] ||= Eco::API::Common::People::PersonFactory.new(schema: schema)
       end
 
       # Allows to use the defined parsers
       # @note the use of these method requires to know which is the expected format of `source`
       # @param attr [String] type (`Symbol`) or attribute (`String`) to target a specific parser.
       # @param source [Any] source value to be parsed.
-      def parse_attribute(attr, source)
+      # @param phase [Symbol] the phase when this parser should be active.
+      def parse_attribute(attr, source, phase = :internal)
         unless parsers = entry_factory.person_parser
           raise "There are no parsers defined"
         end
         parsers.parse(attr, source)
       end
 
+      # @see Eco::API::Common::People::EntryFactory#export
+      # @param (see Eco::API::Common::People::EntryFactory#export)
       def export(*args)
         entry_factory.export(*args)
       end
 
       # @see Eco::API::Common::People::EntryFactory#new
+      # @param (see Eco::API::Common::People::EntryFactory#new)
       # @return [Ecoportal::API::Internal::Person]
       def new_person(**keyed_args)
         person_factory.new(**keyed_args)
       end
 
@@ -136,10 +148,11 @@
       def new_entry(data, dependencies: {})
         entry_factory.new(data, dependencies: dependencies)
       end
 
       # @see Eco::API::Common::People::EntryFactory#entries
+      # @param (see Eco::API::Common::People::EntryFactory#entries)
       # @return [Eco::API::Common::People::Entries] collection of entries.
       def entries(*args)
         entry_factory.entries(*args).tap do |collection|
           logger.info("Loaded #{collection.length} input entries.")
         end
@@ -157,61 +170,87 @@
       # @note requires `session.config.people.discarded_file` to be defined.
       # @return [Eco::API::Common::People::Entries] collection of entries.
       def discarded_entries
         return @discarded_entries if instance_variable_defined?(:@discarded_entries)
         file = config.people.discarded_file
-        file = file_manager.dir.file(file)
+        fatal("You have not specified the 'discarded_people_file'") unless file = file_manager.dir.file(file)
         @discarded_entries = csv_entries(file)
       end
+      # @!endgroup
 
+      # @!group Session workflow and batch job launces
+
+      # Opens up the `workflow` configuration
       def workflow(io:)
         config.workflow.tap do |wf|
           yield(wf, io) if block_given?
         end
       end
 
+      # Does merge `Eco::API::UseCases::DefaultCases` with the custom cases.
+      # @return [Eco::API::UseCases]
       def usecases
-        @usecases ||= Eco::API::UseCases::DefaultCases.new.merge(config.usecases)
+        @usecases ||= config.usecases.dup.tap do |cases|
+          all_cases = Eco::API::UseCases::DefaultCases.new.merge(config.usecases)
+          cases.merge(all_cases)
+        end
       end
 
+      # Set of helpers to simplify your code
+      # @see Eco::API::MicroCases
+      # @return [Eco::API::MicroCases]
+      def micro
+        @micro    ||= Eco::API::MicroCases.new(enviro)
+      end
+
       def post_launch
         @post_launch ||= config.post_launch.select(usecases)
       end
 
+      # @see Eco::API::UseCases::Case#launch
       def process_case(name, io: nil, type: nil, **params)
         args = { session: self }.merge(params)
         usecases.case(name, type: type).launch(io: io, **args)
       end
 
+      # @return [Eco::API::Session::Batch::JobsGroups]
       def job_groups
         @job_groups ||= Batch::JobsGroups.new(enviro)
       end
 
+      # @return [Eco::API::Session::Batch::Jobs]
       def job_group(name, order: :last)
         case
         when job_groups.exists?(name)
           job_groups[name]
         else
           job_groups.new(name, order: order)
         end
       end
 
-      # shortcut to create a job of certain type within a group
+      # Shortcut to create a job of certain type within a group
+      # @return [Eco::API::Session::Batch::Job]
       def new_job(group, name, type, usecase, sets = [:core, :details, :account])
         job_group(group).new(name, usecase: usecase, type: type, sets: sets)
       end
 
+      # @see Eco::API::Session::Batch::JobsGroups#launch
       def jobs_launch(simulate: false)
         job_groups.launch(simulate: simulate)
       end
 
+      # @see Eco::API::Session::Batch::JobsGroups#summary
       def summary
         job_groups.summary
       end
+      # @!endgroup
 
+      # @!group Additional resources
+
       # Sends an email
       # @see Eco::API::Common::Session::Mailer#mail
+      # @param (see Eco::API::Common::Session::Mailer#mail)
       def mail(**kargs)
         if mailer?
           mailer.mail(**kargs)
         else
           logger.error("You are trying to use the mailer, but it's not configured")
@@ -230,11 +269,11 @@
       # @param link [Boolean] **return** _link(s)_ (`true`) or _path(s)_ (`false`: default)
       # @return [String, Array<String>] either paths to S3 objects if `link` is `false`, or _link_ otherwise
       def s3upload(content: nil, file: nil, directory: nil, recurse: false, link: false)
         if s3uploader?
           if content == :target
-            path = self.do.s3upload_targets
+            path = micro.s3upload_targets
           elsif content && file
             path = s3uploader.upload(file, content)
           elsif file
             path = s3uploader.upload_file(file)
           elsif directory
@@ -247,22 +286,14 @@
         else
           logger.error("You are trying to use S3 uploader, but it's not configured")
           nil
         end
       end
+      # @!endgroup
 
       private
 
-      # Helper to state the abilities that a person should have with given their usergroups
-      def presets_factory
-        @presets_factory ||= Eco::API::Organization::PresetsFactory.new({
-          presets_custom: file_manager.dir.file(config.people.presets_custom, should_exist: true),
-          presets_map:    file_manager.dir.file(config.people.presets_map,    should_exist: true),
-          enviro:         enviro
-        })
-      end
-
       # Comparer to state if 2 schemas are different
       def same_schema? (schema1, schema2)
         eq   = schema1&.id == schema2&.id
         eq ||= schema1&.name&.downcase == schema2&.name&.downcase
         schema1 && schema2 && eq
@@ -289,6 +320,5 @@
   end
 end
 
 require_relative 'session/config'
 require_relative 'session/batch'
-require_relative 'session/task'