ecoportal-api-v2 1.1.5 → 1.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3dba4cd5253cab4decdb13d328fb6f42378dd9f04a6bd9a1f3a29d92b1ea742
-  data.tar.gz: 711ce1261bb5ca760a6c677d76763b83b1348a224e25479fbb385c603bef0bc8
+  metadata.gz: 65194be30f026aa431874543d6905b5704ea081c6a3c9ef0bf9741142c4c4253
+  data.tar.gz: 398eaeb83ea38386670715c0fa83144004abdbd8c7edfd8581ecb7b157c8d205
 SHA512:
-  metadata.gz: cf681ae84a49b6524ddc291a3d73adebbb69fd22a205dd2f8c031e13ee193924de033cb3527c5187a35e68e8c16259e9594cb54822d0c9e09622ac0891cead3b
-  data.tar.gz: 4eafbc2ff96d1d617f59422f9b06ee05db7360206669403d5defd54ac005c7117edb44ca51e6f9606cd16b7c28f305de0e51badcc89762d1fa0bba0338622253
+  metadata.gz: 0761f2079d2493f6fef928f846daf4b6b0413838c4f1252c8cf31742284fc5bcfc0e8d6dbd635f2659b37a34a6b90c09ed42f7db781c868a635188354dbe4bbd
+  data.tar.gz: c979ae5a583898d47c1b8501d19ea651f31013a78461008c4ed6eff69c6b1a271c2c812dbbc2a52bc82d90b7caf67e9a286e8d488639eb8bd5a8fd6678c91659

data/CHANGELOG.md

@@ -1,12 +1,34 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.1.6] - 2024-02-xx
+## [1.1.8] - 2024-03-xx
 
 ### Added
 ### Changed
 ### Fixed
 
+## [1.1.7] - 2024-03-xx
+
+### Added
+  - `Ecoportal::API::Common::Concerns::Benchmarkable`
+  - `Ecoportal::API::Common::Conent::CollectionModel`
+    - added ability to define **default** value for `read_only`
+
+### Fixed
+  - `Ecoportal::API::Common::Content::CollectionModel` tidied up item `klass` scoping
+    - **added** some benchmarking too
+    - memoize `@_items`
+
+## [1.1.6] - 2024-02-29
+
+### Added
+  - A bit of **specs** on object retrieval for `Ecoportal::API::Common::Conent::CollectionModel`
+  - `Ecoportal::API::Registers::PageResult` exposed `membranes`
+    - with new object `Ecoportal::API::Registers::PageResult::MembraneDroplet`
+
+### Fixed
+  - `Ecoportal::API::Common::Conent::CollectionModel`
+
 ## [1.1.5] - 2024-02-03
 
 ### Changed

data/README.md

@@ -20,3 +20,8 @@ And then execute:
 Or install it yourself as:
 
     $ gem install ecoportal-api-v2
+
+
+## Changelog
+
+See {file:CHANGELOG.md} for a list of changes.

data/lib/ecoportal/api/common/concerns/benchmarkable.rb

@@ -0,0 +1,160 @@
+module Ecoportal
+  module API
+    module Common
+      module Concerns
+        # @note While benchmarking with multi-thread gives correct results
+        #   for top unique block, will calculate the real time of each individual
+        #   thread, which is way higher than a single thread. However, as they
+        #   run in parallel, the total time would be the valid reference.
+        module Benchmarkable
+          private
+
+          def benchmark_enabled?
+            @benchmark_enabled = true if @benchmark_enabled.nil?
+            @benchmark_enabled
+          end
+
+          def benchmarking(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            benchmark_mem(ref, print: false) do
+              benchmark_time(ref, print: false) do
+                yield
+              end
+            end.tap do
+              puts "\n#{bench_summary_ref(ref)}" if print
+            end
+          end
+
+          def benchmark_mem(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            memory_before = memory_usage
+            yield.tap do
+              memory_after = memory_usage
+              mb_footprint = ((memory_after - memory_before) / 1024.0).round(2)
+              bench_add_mem(ref, mb_footprint)
+              puts bench_str_mem(mb, ref: ref, reffix: true) if print
+            end
+          end
+
+          def benchmark_time(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            result = nil
+            time   = benchmark.realtime do
+              result = yield
+            end.round(2)
+            result.tap do
+              bench_add_time(ref, time)
+              puts bench_str_time(time, ref: ref, reffix: true) if print
+            end
+          end
+
+          def benchmark_summary(ref = nil)
+            return '' unless benchmark_enabled?
+            return bench_summary_ref(ref) unless ref == :all
+
+            bench.keys.each_with_object([]) do |ref, out|
+              out << bench_summary_ref(ref)
+            end.join("\n")
+          end
+
+          def bench_summary_ref(ref = nil)
+            ref_lines = bench_summary_ref_lines(ref)
+            "- #{ref}\n" + "  • " + ref_lines.join("\n  • ")
+          end
+
+          def bench_summary_ref_lines(ref = nil)
+            ref_bench = bench_get(ref)
+            [
+              bench_str_time(*ref_bench[:time].values_at(:avg, :cnt), ref: ref),
+              bench_str_mem(*ref_bench[:mem].values_at(:avg, :cnt), ref: ref)
+            ]
+          end
+
+          def benchmark
+            require 'benchmark'
+            Benchmark
+          end
+
+          def bench
+            @bench ||= {}
+          end
+
+          def bench_add_mem(ref, mem)
+            bench_data_push(bench_get(ref)[:mem], mem)
+          end
+
+          def bench_add_time(ref, time)
+            bench_data_push(bench_get(ref)[:time], time)
+          end
+
+          def bench_get(ref)
+            bench[ref] ||= {
+              time: bench_data,
+              mem:  bench_data
+            }
+          end
+
+          def bench_data
+            {
+              avg: nil,
+              cnt: 0
+            }
+          end
+
+          def bench_data_push(data, value)
+            total       = value + ( (data[:avg] || 0) * data[:cnt])
+            data[:cnt] += 1
+            data[:avg]  = (total / data[:cnt]).round(3)
+            data
+          end
+
+          def bench_str_mem(mem, count = nil, ref: nil, reffix: false)
+            ref = reffix ? ref : nil
+            msg = [ref, 'Memory'].compact.join(' -- ')
+            cnt = count ? " (cnt: #{count})" : ''
+            "#{msg}: #{mem} MB#{cnt}"
+          end
+
+          def active_support_duration?
+            return false unless Kernel.const_defined?(:ActiveSupport)
+            ActiveSupport.const_defined?(:Duration, false)
+          end
+
+          def bench_str_time(time, count = nil, ref: nil, reffix: false)
+            ref      = reffix ? ref : nil
+            msg      = [ref, 'Time'].compact.join(' -- ')
+            total    = (time * count).round(2)
+            str_desc = ''
+            if active_support_duration? && total >= 60
+              duration = ActiveSupport::Duration.build(total.round)
+              str_desc = ": #{duration_to_s(duration)}"
+            end
+            cnt      = count ? " (cnt: #{count}; sum: #{total} s#{str_desc})" : ''
+            "#{msg}: #{time} s#{cnt}"
+          end
+
+          def duration_to_s(value)
+            return "" unless active_support_duration?
+            return "" if value.nil?
+
+            raise ArgumentError, "Expecint ActiveSupport::Duration. Given: #{value.class}" unless value.is_a?(ActiveSupport::Duration)
+            parts = value.parts.map {|pair| pair.reverse.join(" ")}
+            return parts.first if parts.length == 1
+            [parts[..-2].join(", "), parts.last].join(" and ")
+          end
+
+          # @return [Integer] total memory used by this process in KB
+          def memory_usage
+            if Gem.win_platform?
+              wmem = `wmic process where processid=#{Process.pid} get WorkingSetSize | findstr "[0-9]"`
+              return 0 unless wmem
+              wmem.lines.first.chop.strip.to_i / 1024.0
+            else
+              `ps -o rss= -p #{Process.pid}`.to_i
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/concerns.rb

@@ -0,0 +1,10 @@
+module Ecoportal
+  module API
+    module Common
+      module Concerns
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/common/concerns/benchmarkable'

data/lib/ecoportal/api/common/content/array_model.rb

@@ -34,7 +34,7 @@ module Ecoportal
 
           inheritable_class_vars :order_matteres, :uniq
 
-          def initialize(doc = [], parent: self, key: nil, read_only: false)
+          def initialize(doc = [], parent: self, key: nil, read_only: self.class.read_only?)
             super(doc, parent: parent, key: key, read_only: read_only)
           end
 

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -6,11 +6,12 @@ module Ecoportal
         # @note to be able to refer to the correct element of the Collection,
         #   it is required that those elements have a unique `key` that allows to identify them
         class CollectionModel < Content::DoubleModel
-
           class << self
             attr_writer   :klass
             attr_accessor :order_matters, :order_key
 
+            # The attr that has been defined as `passkey`
+            # in the item class
             def items_key
               @items_key ||= "id"
             end
@@ -22,26 +23,46 @@ module Ecoportal
             # Resolves to the nuclear `Class` of the elements
             # @note
             #   - use block to define `klass` callback
+            # @note When `klass` is resolved, if the items are of type
+            #   `DoubleModel`, it sets on the collection class the `items_key`
+            # @note when `klass` is directly resolved (not via doc) only once
+            #    it will set @klass as resolved and will use this class from now on.
+            #    This is an optimization to cut class lookups
             # @param value [Hash] base `doc` (raw object) to create the object with
             # @yield [doc] identifies the target `class` of the raw object
             # @yieldparam doc [Hash]
             # @yieldreturn [Klass] the target `class`
             # @return [Klass] the target `class`
             def klass(value = NOT_USED, &block)
-              if block
-                @klass = block
-                block.call(value) if value != NOT_USED
-              elsif used_param?(value)
-                if @klass.is_a?(Proc)
-                  @klass.call(value)
-                else
-                  resolve_class(@klass, exception: false)
-                end
+              @klass = block if block_given?
+
+              if @klass && !@class.is_a?(Proc)
+                @klass = resolve_class(@klass, exception: false) unless @klass.is_a?(Class)
+                @klass
+              elsif @klass.is_a?(Proc) && used_param?(value)
+                @klass.call(value)
               else
-                resolve_class(@klass, exception: false)
+                @klass
+              end.tap do |result|
+                next unless result.is_a?(Class)
+                next unless result < Ecoportal::API::Common::Content::DoubleModel
+                self.items_key = result.key
               end
             end
 
+            # @return [Boolean] are there the factory logics to build item objects defined?
+            def klass?
+              @klass || @new_item
+            end
+
+            # Optimization
+            def new_item_class_based?
+              return false if @new_item.is_a?(Proc)
+              return false if @klass.is_a?(Proc)
+              return true  if klass.is_a?(Class)
+              false
+            end
+
             # Generates a new object of the target class
             # @note
             #   - use block to define `new_item` callback, which will prevail over `klass`
@@ -51,29 +72,24 @@ module Ecoportal
             # @yield [doc, parent, key] creates an object instance of the target `klass`
             # @yieldparam doc [Hash]
             # @yieldreturn [Klass] instance object of the target `klass`
+            # @parent [CollectionModel] the parent of the new item
+            # @key [Symbol, String] the key value to access the item within collection
+            #   Please observe that items in a CollectionModel are identified via their key attr.
+            #   Meaning that there is actually no need to define this argument.
             # @return [Klass] instance object of the target `klass`
             def new_item(doc = NOT_USED, parent: nil, key: nil, read_only: false, &block)
-              if block
-                @new_item = block
-              elsif used_param?(doc)
-                raise "You should define either a 'klass' or a 'new_item' callback first" unless klass?
-                if @new_item
-                  @new_item.call(doc, parent, key)
-                else
-                  if target_class = self.klass(doc)
-                    doc.is_a?(target_class) ? doc : target_class.new(doc, parent: parent, key: key, read_only: read_only)
-                  else
-                    raise "Could not find a class for: #{doc}"
-                  end
-                end
-              else
-                raise "To define the 'new_item' callback (factory), you need to use a block"
-              end
-            end
+              return (@new_item = block; nil) if block_given
 
-            # @return [Boolean] are there the factory logics to build item objects defined?
-            def klass?
-              @klass || @new_item
+              msg = "To define the 'new_item' callback (factory), you need to use a block"
+              raise msg unless used_param?(doc)
+              msg = "You should define either a 'klass' or a 'new_item' callback first"
+              raise msg unless klass?
+              return @new_item.call(doc, parent, key)    if @new_item.is_a?(Proc)
+
+              raise "Could not find a class for: #{doc}" unless target_class = klass(doc)
+              return doc if doc.is_a?(target_class)
+
+              target_class.new(doc, parent: parent, key: key, read_only: read_only)
             end
 
             def doc_class(name)
@@ -127,7 +143,17 @@ module Ecoportal
                 #print "{{#{p}}}"
               end
             else
-              raise UnlinkedModel.new("Can't find child: #{value}")
+              show_str = \
+                case value
+                when Hash
+                  value.pretty_inspect
+                when Content::DoubleModel
+                  "#{value} with key: #{value.class.key} (items_key: #{self.class.items_key})"
+                else
+                  value
+                end
+
+              raise UnlinkedModel, "Can't find child: #{show_str}"
             end
           end
 
@@ -147,6 +173,7 @@ module Ecoportal
               _doc_items.each do |item_doc|
                 elements << new_item(item_doc)
               end
+              @_items = elements if read_only?
             end
           end
 
@@ -256,7 +283,11 @@ module Ecoportal
           private
 
           def new_item(value)
-            self.class.new_item(value, parent: self, read_only: self._read_only)
+            if self.class.new_item_class_based?
+              self.class.klass.new(value, parent: self, read_only: self._read_only)
+            else
+              self.class.new_item(value, parent: self, read_only: self._read_only)
+            end
           end
 
           # Helper to remove tracked down instance variables

data/lib/ecoportal/api/common/content/double_model.rb

@@ -28,6 +28,8 @@ module Ecoportal
               !!key
             end
 
+            # key property (and method) of this model
+            # @note this is auto-set when `passkey` is used
             def key=(value)
               @key = value.to_s.freeze
             end
@@ -36,6 +38,16 @@ module Ecoportal
               uid(length)
             end
 
+            def read_only?
+              @read_only = false if @read_only.nil?
+              @read_only
+            end
+
+            # Be able to define if a class should be read-only
+            def read_only!
+              @read_only = true
+            end
+
             # Same as `attr_reader` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
             # @param methods [Array<Symbol>] the method that exposes the value
@@ -72,7 +84,7 @@ module Ecoportal
             # This method is essential to give stability to the model
             # @note `Content::CollectionModel` needs to find elements in the doc `Array`.
             #  The only way to do it is via the access key (i.e. `id`). However, there is
-            #  no chance you can avoid invinite loop for `get_key` without setting an
+            #  no chance you can avoid infinite loop for `get_key` without setting an
             #  instance variable key at the moment of the object creation, when the
             #  `doc` is firstly received
             # @param method [Symbol] the method that exposes the value
@@ -174,7 +186,7 @@ module Ecoportal
 
                 define_method method do
                   return instance_variable_get(var) if instance_variable_defined?(var)
-                  new_obj = dim_class.new(parent: self, key: method, read_only: self._read_only)
+                  new_obj = dim_class.new(parent: self, key: method, read_only: self.read_only?)
                   variable_set(var, new_obj)
                 end
               end
@@ -200,7 +212,7 @@ module Ecoportal
             # @param read_only [Boolean] whether or not should try to **work around** items `klass` missing a `key`
             #   - If set to `true` this is meant only for read purposes (won't be able to successufully insert)
             def embeds_many(method, key: method, klass: nil, enum_class: nil,
-              order_matters: false, order_key: nil, read_only: false)
+              order_matters: false, order_key: nil, read_only: self.read_only?)
               if enum_class
                 eclass = enum_class
               elsif klass
@@ -208,6 +220,7 @@ module Ecoportal
                   dim_class.klass         = klass
                   dim_class.order_matters = order_matters
                   dim_class.order_key     = order_key
+                  dim_class.read_only! if read_only
                 end
               else
                 raise "You should either specify the 'klass' of the elements or the 'enum_class'"
@@ -222,7 +235,7 @@ module Ecoportal
 
             private
 
-            def embed(method, key: method, nullable: false, multiple: false, klass:, read_only: false, &block)
+            def embed(method, key: method, nullable: false, multiple: false, klass:, read_only: self.read_only?, &block)
               method = method.to_s.freeze
               var    = instance_variable_name(method).freeze
               k      = key.to_s.freeze
@@ -249,7 +262,7 @@ module Ecoportal
                   end
                 end
 
-                embedded_class.new(doc[k], parent: self, key: k, read_only: self._read_only || read_only).tap do |obj|
+                embedded_class.new(doc[k], parent: self, key: k, read_only: self.read_only? || read_only).tap do |obj|
                   variable_set(var, obj)
                 end
               end
@@ -261,11 +274,12 @@ module Ecoportal
             end
           end
 
-          inheritable_class_vars :forced_model_keys, :key
+          inheritable_class_vars :forced_model_keys, :key, :read_only
 
+          # `_key` refers to the parent's property that links to this model
           attr_reader :_parent, :_key, :_read_only
 
-          def initialize(doc = {}, parent: self, key: nil, read_only: false)
+          def initialize(doc = {}, parent: self, key: nil, read_only: self.class.read_only?)
             @_dim_vars  = []
             @_parent    = parent || self
             @_key       = key    || self
@@ -284,6 +298,12 @@ module Ecoportal
             end
           end
 
+          # @note `read_only` allows for some optimizations, such as storing values
+          #   in instance variables, for optimization purposes
+          def read_only?
+            @_read_only
+          end
+
           def root
             return self if is_root?
             _parent.root
@@ -321,6 +341,8 @@ module Ecoportal
             if is_root?
               @doc
             else
+              # transform parent's `_key` to this object into a
+              # path key that can rerieve from the parents's doc
               _parent.doc.dig(*[_doc_key(_key)].flatten)
             end
           end
@@ -403,6 +425,9 @@ module Ecoportal
             !!defined?(@doc)
           end
 
+          # Both requisites
+          # @note that for optimization purposes, `@doc` var may be used when
+          #   the object is `read_only?`
           def is_root?
             _parent == self && doc_var?
           end

data/lib/ecoportal/api/common.v2.rb

@@ -5,4 +5,5 @@ module Ecoportal
   end
 end
 
+require 'ecoportal/api/common/concerns'
 require 'ecoportal/api/common/content'

data/lib/ecoportal/api/v2/registers/page_result/membrane_droplet.rb

@@ -0,0 +1,15 @@
+module Ecoportal
+  module API
+    class V2
+      class Registers
+        class PageResult
+          class MembraneDroplet < Common::Content::DoubleModel
+            passkey     :ref
+            passthrough :label, :type, :value
+            passthrough :field_configuration_id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v2/registers/page_result.rb

@@ -12,10 +12,14 @@ module Ecoportal
           passthrough :mould_counter
 
           class_resolver :stages_class, "Ecoportal::API::V2::Registers::StagesResult"
-          embeds_many    :stages, enum_class: :stages_class
-        end
+          embeds_many    :stages, enum_class: :stages_class, read_only: true
 
+          class_resolver :mem_droplet, "Ecoportal::API::V2::Registers::PageResult::MembraneDroplet"
+          embeds_many    :membranes, klass: :mem_droplet, read_only: true
+        end
       end
     end
   end
 end
+
+require_relative 'page_result/membrane_droplet'

data/lib/ecoportal/api/v2_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GEM2_VERSION = "1.1.5"
+    GEM2_VERSION = "1.1.7"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.7
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-02 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -156,7 +156,6 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
@@ -168,6 +167,8 @@ files:
 - ecoportal-api-v2.gemspec
 - lib/ecoportal/api-v2.rb
 - lib/ecoportal/api/common.v2.rb
+- lib/ecoportal/api/common/concerns.rb
+- lib/ecoportal/api/common/concerns/benchmarkable.rb
 - lib/ecoportal/api/common/content.rb
 - lib/ecoportal/api/common/content/array_model.rb
 - lib/ecoportal/api/common/content/class_helpers.rb
@@ -242,6 +243,7 @@ files:
 - lib/ecoportal/api/v2/people.rb
 - lib/ecoportal/api/v2/registers.rb
 - lib/ecoportal/api/v2/registers/page_result.rb
+- lib/ecoportal/api/v2/registers/page_result/membrane_droplet.rb
 - lib/ecoportal/api/v2/registers/register.rb
 - lib/ecoportal/api/v2/registers/search_results.rb
 - lib/ecoportal/api/v2/registers/stage_result.rb

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.5.1
-before_install: gem install bundler -v 1.16.1