ecoportal-api-graphql 0.4.7 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b968296728e5236f8a3aae38661d2caa27467e40c20e5b3d81daf436f02d48dd
-  data.tar.gz: bbd52cdb4e42afce5e2e7c7712c57d8829d0837ab3f7adc5ef3d5259c6640d8b
+  metadata.gz: d43b5c70e8ce94e96f2028bcc80b6bdf45ac8f78afa7a1689b2149e2175d39db
+  data.tar.gz: c7e932aea0d5b4976677cecb565a64c3523b2cd8af2fac49e7ecf35f8265d636
 SHA512:
-  metadata.gz: f1449e74769d6006fd330316f8741525a5c972f9a23654ab4ad08faf9f59e34ad14075e5bf30b1123da20a0cdef8023b19a4e286255d15923118ee92571af11e
-  data.tar.gz: 01605be05f707c622ce48f03c722b9c638287b32d57c64e98241115c7ed39d57041809f6445984410d39cb1fce555edf760f56020d6c3fd3549bf9a8ceeaebb6
+  metadata.gz: dbd441319d44294084754bcc03f8660b6361930617ae23bf66faeae3d2f204d2c28d0523b63fe0985629cd196c7445ff0eaa01c18740baf02522c7c37f982f65
+  data.tar.gz: 9cae64f7110b5df6e3995ff36af69220b3e19cdd1cb7f8e1914128fdffadea5a916e429b2e28e009be618a709d5765b51419d441f1fd576135ae74f19a1d6292

data/.gitignore

@@ -19,4 +19,6 @@ Gemfile.lock
 # rspec failure tracking
 .rspec_status
 scratch.rb
-tests/.byebug_history
+tests/.byebug_history
+
+.solargraph.yml

data/.rubocop.yml

@@ -4,13 +4,15 @@ AllCops:
     - 'config/routes.rb'
   NewCops: enable
 
+Metrics/ClassLength:
+  Max: 350
+Metrics/ModuleLength:
+  Max: 400
+Metrics/MethodLength:
+  Max: 100
 Metrics/BlockLength:
   CountAsOne: ['array', 'heredoc', 'method_call']
   Max: 50
-Metrics/MethodLength:
-  Max: 50
-Metrics/ClassLength:
-  Max: 200
 Metrics/AbcSize:
   Max: 30
 Metrics/ParameterLists:

data/CHANGELOG.md

@@ -9,19 +9,44 @@ All notable changes to this project will be documented in this file.
   - Analyse how to "DSL" currentOrganization.action.activities
     - review `path` tracking
 
-## [0.4.8] - 2025-04-xx
+## [1.1.2] - 2025-05-xx
 
 ### Added
 
-- `page.id` to Action linked resources.
+### Changed
 
-## [0.4.7] - 2025-04-02
+### Fixed
+
+## [1.1.1] - 2025-05-14
 
 ### Added
 
+- `MemberChanges` helpers for `Base::ContractorEntity`
+- Custom **Diff** logic that can be used in GraphQL content:
+  - `Common::GraphQL::Model::Diffable::HashDiffNesting`
+    - Reused from `HashDiffPatch` (`ecoportal-api-v2`):
+      1. It does not use `patch_ver`, but rather just `id` property alone.
+      2. The _operation_ property has been renamed to `api_operation` (to ensure no collisions). And the operation types are symbols, and renamed to: `:delete`, `:update` and `:create`. This can show up to be useful when, for instance, reusing the output of `#as_update` to generate actual input objects (i.e. `#as_input`) that feed some GraphQL query.
+      3. The _data_ property has been renamed to `change_data`.
+      4. `Hash` **keys** are of type `Symbol`.
+  - `Common::GraphQL::Model::Diffable::DiffService`. In a GraphQL context, this aims to be able to implement a function called `#as_input` (equivalent to `#as_update`):
+      1. It uses the `HashDiffNesting` helpers.
+      2. It has capability to `ignore` certain keys.
+      3. It can calculate **diff** excluding nested models (i.e. those that are `root?` and, therefore, not part of the changed target model). This functionality is an optimization to `cascaded_callbacks` throughout the nested models.
+
 ### Changed
 
-### Fixed
+- `Common::GraphQL::Model::Diffable` by using `Diffable::DiffService` (with `cascaded_callbacks` implementation).
+  - `#as_update`
+  - `#dirty?`
+- upgraded `ecoportal-api` gem
+- updraded `ecoportal-api-v2` gem
+
+## [0.4.7] - 2025-04-02
+
+### Added
+
+- `page.id` to Action linked resources.
 
 ## [0.4.6] - 2025-04-02
 

data/ecoportal-api-graphql.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
 
   spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.9'
-  spec.add_dependency 'ecoportal-api-v2', '~> 2.0',   '>= 2.0.16'
+  spec.add_dependency 'ecoportal-api-v2', '~> 3.1',   '>= 3.1.1'
   spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
 end
 

data/lib/ecoportal/api/common/graphql/hash_helpers.rb

@@ -3,6 +3,12 @@ module Ecoportal
     module Common
       module GraphQL
         module HashHelpers
+          class << self
+            def included(base)
+              base.send(:include, InstanceMethods)
+            end
+          end
+
           module InstanceMethods
             def keys_to_sym_deep(value)
               transform_keys_deep(value, &:to_sym)
@@ -91,17 +97,7 @@ module Ecoportal
             end
           end
 
-          module ClassMethods
-          end
-
-          class << self
-            include InstanceMethods
-
-            def included(base)
-              base.send(:include, InstanceMethods)
-              base.extend(ClassMethods)
-            end
-          end
+          extend InstanceMethods
         end
       end
     end

data/lib/ecoportal/api/common/graphql/model/as_input.rb

@@ -3,10 +3,21 @@ module Ecoportal
     module Common
       module GraphQL
         class Model
+          # @todo
+          #   1. `#as_input` vs `#to_input` **or** named argument `klass`
+          #     One gets the `input` to be already used in a mutation query.
+          #     The other gets the `Input` class object out of the `Base/Model`.
+          #     - To figure out when `as_update` should be called.
+          #   2. Each Base/Model should have its `Input` class counterpart.
+          #     This could be auto-inflected (via namespace constant lookup)
+          #     at some point.
+          #   3. Think if a service class can be used to this purpose
+          #     (i.e. decorator of DiffService).
           module AsInput
             class << self
               def included(base)
                 super
+
                 base.send(:include, Model::Diffable)
                 base.extend ClassMethods
               end

data/lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb

@@ -0,0 +1,47 @@
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  class ClassicDiffService
+    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
+
+    attr_reader :subject
+
+    def initialize(subject, ignore: [])
+      msg  = 'Expecting Ecoportal::API::Common::Content::DoubleModel. '
+      msg << "Given: #{subject.class}"
+      raise ArgumentError, msg unless subject.is_a?(Ecoportal::API::Common::Content::DoubleModel)
+
+      @subject  = subject
+      @ignored  = to_a(ignore)
+    end
+
+    def diff(ignore: [])
+      classic_diff(ignore: ignore)
+    end
+
+    protected
+
+    def classic_diff(ignore: [])
+      change_diff(
+        curr_doc,
+        prev_doc,
+        ignore: to_a(ignored, ignore)
+      )
+    end
+
+    private
+
+    attr_reader :ignored
+
+    def curr_doc(target = subject)
+      return target.as_json if target.respond_to?(:as_json)
+      return target.doc     if target.respond_to?(:doc)
+
+      raise "Can't fetch underlying document for instance of #{target.class}."
+    end
+
+    def prev_doc(target = subject, flat: flat?)
+      return target.original_doc if target.respond_to?(:original_doc)
+
+      raise "Can't fetch original underlying model for instance of #{target.class}."
+    end
+  end
+end

data/lib/ecoportal/api/common/graphql/model/diffable/diff_service.rb

@@ -0,0 +1,180 @@
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  class DiffService < ClassicDiffService
+    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
+    include Ecoportal::API::Common::GraphQL::HashHelpers
+
+    def initialize(subject, flat: false, ignore: [])
+      super(subject, ignore: ignore)
+
+      @flat = flat
+    end
+
+    def flat?
+      @flat
+    end
+
+    # @param flat [Boolean] whethere it should skip nested models.
+    # @param cascaded [Boolean] whether it should cascade the calls through
+    #   the nested models.
+    #   - When `flat` is `true` will only cascade the 1st level of nested models.
+    #   - When `flat` is `false` will do a full cascade.
+    def diff(flat: flat?, ignore: [])
+      classic_diff(
+        flat:   true,
+        ignore: ignore
+      ).then do |value|
+        next value if flat
+
+        diff_reduce(
+          value,
+          ignore: ignore
+        )
+      end
+    end
+
+    protected
+
+    def classic_diff(flat: flat?, ignore: [])
+      change_diff(
+        curr_doc(flat: flat),
+        prev_doc(flat: flat),
+        ignore: to_a(ignored, ignore)
+      )
+    end
+
+    # @note it calls `as_update` for nested / cascaded attributes, which in turn
+    #   will use this `DiffService`. Therefore, we aim for a first flat classic diff,
+    #   onto `self`, and cascaded callbacks for the nested attributes.
+    #     - This will translate into `key_path` being lost on each jump between
+    #       `#as_update` and `DiffService#diff`.
+    #     - The `result` object regards, therefore, to the **current level** alone.
+    #       With the aim of building it up (accumulating through the call chain).
+    def diff_reduce(init = {}, ignore: [])
+      subject.cascaded_reduce(init, recurs: false) do |result, obj, _key, key_path, _trace|
+        next result if key_path.empty? # first iteration already done
+        next result if obj == subject  # first call had done it (same as above: path relative)
+
+        dig_delete!(result, key_path) if dig_path?(result, key_path)
+
+        # discard rooted (i.e. read_only) objects from the diff.
+        next result if root?(obj)
+        next result unless dig_path?(result, key_path)
+        next result unless obj.respond_to?(:as_update)
+
+        value = obj.as_update(ignore: ignore)
+
+        dig_set!(
+          result,
+          key_path,
+          value
+        )
+
+        result
+      end
+    end
+
+    # PROBLEM: trace can't be used with knowing if it's the root of the call!
+    # see `#cascaded_reduce` (when calling `_cascaded_attributes_trace`).
+    def diff_reduce_with_as_update_and_trace(init = {}, ignore: [], trace: {})
+      subject.cascaded_reduce(init, recurs: false, trace: trace) do |result, obj, _key, key_path, _trace|
+        next result if key_path.empty? # first iteration already done
+        next result if obj == subject  # first call had done it
+
+        dig_delete!(result, key_path) if dig_path?(result, key_path)
+
+        # discard rooted (i.e. read_only) objects from the diff.
+        next result if root?(obj)
+        next result unless dig_path?(result, key_path)
+        next result unless obj.respond_to?(:as_update)
+
+        value = obj.as_update(ignore: ignore)
+
+        dig_set!(
+          result,
+          key_path,
+          value
+        )
+
+        result
+      end
+    end
+
+    # FAILS to CALL #as_update on each object!!!
+    def diff_reduce_preserve_keys(init, flat: flat?, ignore: [])
+      subject.cascaded_reduce(init, recurs: !flat) do |result, obj, _key, key_path, _trace|
+        # discard rooted (i.e. read_only) objects from the diff.
+        if root?(obj)
+          dig_delete!(result, key_path)
+        else
+          value = classic_diff(
+            obj,
+            flat:   true,
+            ignore: ignore
+          )
+
+          dig_set!(result, key_path, value)
+        end
+
+        result
+      end
+    end
+
+    def cascaded_diff(flat: flat?, ignore: [])
+      subject.cascaded_callback(
+        method: :as_update,
+        kargs:  {
+          ignore: to_a(ignored, ignore),
+          flat:   flat
+        },
+        recurs: !flat
+      ) do |result, value, key_path, obj|
+        result.tap do
+          # on first call key_path is empty
+          next result if key_path.empty? # this condition isn't met, first call doesn't yield.
+
+          # discard rooted (i.e. read_only) objects from the diff.
+          if root?(obj)
+            dig_delete!(result, key_path)
+          else
+            dig_set!(result, key_path, value)
+          end
+        end
+      end
+    end
+
+    private
+
+    attr_reader :ignored
+
+    def root?(obj)
+      return false unless obj.respond_to?(:root?)
+
+      obj.root?
+    end
+
+    def curr_doc(target = subject, flat: flat?)
+      may_use_flat_diff(flat) { super(target) }
+    end
+
+    def prev_doc(target = subject, flat: flat?)
+      may_use_flat_diff(flat) { super(target) }
+    end
+
+    # Remove nested attributes
+    def may_use_flat_diff(flat = flat?)
+      yield.then do |json|
+        next json unless flat
+
+        doc_with_non_cascaded_attributes(json)
+      end
+    end
+
+    # Remove from `json` doc all the nested properties.
+    def doc_with_non_cascaded_attributes(json)
+      return json unless subject.respond_to?(:_cascaded_doc_keys)
+      return json unless (excluded = subject._cascaded_doc_keys)
+
+      except_keys(json, *excluded)
+    end
+  end
+end

data/lib/ecoportal/api/common/graphql/model/diffable/hash_diff.rb

@@ -1,56 +1,51 @@
 # rubocop:disable Naming/MethodParameterName
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  # @note this is a literal copy of ecoportal-api gem diff function.
+  #   ecoportal-api-graphql uses APIv2 DoubleModel inheritance chain,
+  #   and should rather adapt `HashDiffPatch`
+  module HashDiff
+    ID_KEYS = %w[id].freeze
 
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Model
-          module Diffable
-            module HashDiff
-              class << self
-                def included(base)
-                  super
-                  base.extend ClassMethods
-                end
-              end
+    class << self
+      def included(base)
+        super
 
-              module ClassMethods
-                # @todo: refactor to only reach the current level
-                # @note the aim is to delegate `hash_diff` to the specific classes
-                #   of the model... bulding the payload/input_base in a cascaded
-                #   way (rather than in a one-off way from the top alone).
-                def hash_diff(a, b, ignore: [])
-                  case a
-                  when Hash
-                    {}.tap do |diffed|
-                      a.each do |key, a_value|
-                        b_value    = b && b[key]
-                        no_changes = (a_value == b_value) || ignore.include?(key)
-                        next if !ID_KEYS.include?(key) && no_changes
-
-                        diffed[key] = diff(a_value, b_value, ignore: ignore)
-                        diffed.delete(key) if diffed[key] == {}
-                      end
+        base.send :include, InstanceMethods
+      end
+    end
 
-                      # All keys are IDs, so it's actually blank
-                      return {} if (diffed.keys - ID_KEYS).empty?
-                    end
-                  when Array
-                    return a unless b.is_a?(Array) && a.length == b.length
+    module InstanceMethods
+      # @todo: refactor to only reach the current level
+      # @note the aim is to delegate `hash_diff` to the specific classes
+      #   of the model... bulding the payload/input_base in a cascaded
+      #   way (rather than in a one-off way from the top alone).
+      def diff(a, b, ignore: [])
+        case a
+        when Hash
+          {}.tap do |diffed|
+            a.each do |key, a_value|
+              b_value    = b[key] if b
+              no_changes = (a_value == b_value) || ignore.include?(key)
+              next if !ID_KEYS.include?(key) && no_changes
 
-                    a.map.with_index do |a_value, idx|
-                      b_value = b[idx]
-                      diff(a_value, b_value, ignore: ignore)
-                    end.reject do |el|
-                      el == {}
-                    end
-                  else
-                    a
-                  end
-                end
-              end
+              diffed[key] = diff(a_value, b_value, ignore: ignore)
+              diffed.delete(key) if diffed[key] == {}
             end
+
+            # All keys are IDs, so it's actually blank
+            return {} if (diffed.keys - ID_KEYS).empty?
+          end
+        when Array
+          return a unless b.is_a?(Array) && a.length == b.length
+
+          a.map.with_index do |a_value, idx|
+            b_value = b[idx]
+            diff(a_value, b_value, ignore: ignore)
+          end.reject do |el|
+            el == {}
           end
+        else
+          a
         end
       end
     end

data/lib/ecoportal/api/common/graphql/model/diffable/hash_diff_nesting.rb

@@ -0,0 +1,242 @@
+# rubocop:disable Naming/MethodParameterName
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  # @note this is a literal copy of ecoportal-api-v2 gem `has_diff` function.
+  # @todo the aim is to adapt it by:
+  #   1. Removing the `patch_ver` model ✅
+  #   2. Using symbol keys ✅
+  module HashDiffNesting
+    class << self
+      def included(base)
+        super
+
+        base.send :include, InstanceMethods
+      end
+    end
+
+    META_KEYS  = %i[id].freeze
+    NO_CHANGES = "%not-changed!%".freeze
+
+    module InstanceMethods
+      # The `change data` is built as follows:
+      # 1. detect changes that have occurred translate into one `api_operation` of `OP_TYPE`:
+      #   * `:update`: meaning that the object has changed (existed and has not been removed)
+      #   * `:delete`:  the object has been removed
+      #   * `:create`:     the object is new
+      # 2. at the level of the target object of the model, the object is opened for change
+      # with `id` and `api_operation` as follows:
+      #
+      #    ```json
+      #    {
+      #       "id":            "objectID",
+      #       "api_operation": "OP_TYPE",
+      #       "change_data" {
+      #         "property":      "value",
+      #          "...":          "..."
+      #       }
+      #    }
+      #    ```
+      # 3. the `change_data` property holds the specific changes of the object
+      #   - the properties that have changed
+      # @note
+      #   * there should not be difference between `null` and `""` (empty string)
+      # @param a [Hash] current hash model
+      # @param b [Hash] previous hash model
+      # @return [Hash] a `change data`
+      def change_diff(a, b, ignore: [])
+        ignore = to_a(ignore)
+
+        if b.is_a?(Hash) && !empty?(b) && empty?(a)
+          patch_delete(b)
+        elsif a.is_a?(Hash) && !empty?(a) && empty?(b)
+          patch_new(a, ignore: ignore)
+        elsif a.is_a?(Hash) && b.is_a?(Hash)
+          patch_update(a, b, ignore: ignore)
+        elsif any_array?(a, b)
+          patch_data_array(a, b, ignore: ignore)
+        else
+          a
+        end
+      end
+
+      private
+
+      # Compares `a` as carrying changes of `b`
+      # @return [Hash] change data object with only changes
+      def change_data(a, b = nil, delete: false, ignore: [])
+        {}.tap do |data_hash|
+          next if delete
+
+          a.each do |key, a_value|
+            key = key.to_sym
+
+            next if meta_keys.include?(key)
+            next if ignore.include?(key)
+
+            b_value = nil
+
+            if b&.key?(key)
+              b_value = b[key]
+              next if equal_values?(a_value, b_value)
+            end
+
+            data_hash[key] = change_diff(a_value, b_value)
+
+            data_hash.delete(key) if data_hash[key] == NO_CHANGES
+          end
+
+          return NO_CHANGES if (data_hash.keys - meta_keys).empty?
+        end
+      end
+
+      def patch_delete(b)
+        return NO_CHANGES unless b.is_a?(Hash)
+        return            unless (id = get_id(b, exception: false))
+
+        {
+          id:            id,
+          api_operation: :delete,
+          change_data:   change_data(b, delete: true)
+        }
+      end
+
+      def patch_new(a, ignore: [])
+        return NO_CHANGES unless a.is_a?(Hash)
+        return a          unless (id = get_id(a, exception: false))
+
+        {
+          id:            id,
+          api_operation: :create,
+          change_data:   change_data(a, ignore: ignore)
+        }
+      end
+
+      def patch_update(a, b, ignore: [])
+        return NO_CHANGES unless a.is_a?(Hash)
+        return a          unless (id = get_id(a, exception: false))
+
+        {
+          id:            id,
+          api_operation: :update,
+          change_data:   change_data(a, b, ignore: ignore)
+        }.tap do |update_hash|
+          return nil unless update_hash[:change_data] != NO_CHANGES
+        end
+      end
+
+      def patch_data_array(a, b, ignore: [])
+        return patch_data_nested_array(a, b, ignore: ignore) if nested_array?(a, b)
+
+        patch_data_flat_array(a, b)
+      end
+
+      def patch_data_flat_array(a, b)
+        original_b = b
+        a        ||= []
+        b        ||= []
+
+        same_elements =
+          a.length == b.length &&
+          (a & b).length == b.length
+
+        return a          unless same_elements
+        return NO_CHANGES if original_b
+
+        a
+      end
+
+      def patch_data_nested_array(a, b, ignore: [])
+        a ||= []
+        b ||= []
+
+        # array with nested elements
+        a_ids = array_ids(a)
+        b_ids = array_ids(b)
+
+        del_ids = b_ids - a_ids
+        oth_ids = b_ids & a_ids
+        new_ids = a_ids - b_ids
+
+        arr_delete = del_ids.map do |id|
+          patch_delete(array_id_item(b, id))
+        end.compact
+
+        arr_update = oth_ids.map do |id|
+          patch_update(array_id_item(a, id), array_id_item(b, id), ignore: ignore)
+        end.compact
+
+        arr_new = new_ids.map do |id|
+          patch_new(array_id_item(a, id), ignore: ignore)
+        end.compact
+
+        arr_delete.concat(arr_update).concat(arr_new).tap do |patch_array|
+          # remove data with no `id`
+          patch_array.select! {|item| item.is_a?(Hash)}
+          return NO_CHANGES if patch_array.empty?
+        end
+      end
+
+      def nested_array?(*arr)
+        if arr.length > 1
+          arr.any? {|a| nested_array?(a)}
+        elsif arr.length == 1
+          arr = arr.first || []
+          arr.any? do |item|
+            next false unless item.is_a?(Hash)
+            next true  if item.key?(:id)
+
+            false
+          end
+        else
+          false
+        end
+      end
+
+      def any_array?(a, b)
+        [a, b].any? {|item| item.is_a?(Array)}
+      end
+
+      def get_id(doc, exception: true)
+        id   = nil
+        id ||= doc.id    if doc.respond_to?(:id)
+        id ||= doc['id'] if doc.is_a?(Hash)
+        id ||= doc[:id]  if doc.is_a?(Hash)
+        id ||= doc       if doc.is_a?(String)
+
+        raise 'No ID has been given!' unless id || !exception
+
+        id
+      end
+
+      def meta_keys
+        return self::META_KEYS if respond_to?(:const_get)
+
+        self.class::META_KEYS
+      end
+
+      def equal_values?(a, b)
+        if a.is_a?(String) || b.is_a?(String)
+          a_empty = a.to_s.strip.empty?
+          b_empty = b.to_s.strip.empty?
+
+          return true if a_empty && b_empty
+        end
+
+        a == b
+      end
+
+      def empty?(a)
+        bool   = !a
+        bool ||= a.respond_to?(:empty?) && a.empty?
+        bool
+      end
+
+      def to_a(*values)
+        [values].flatten.compact.uniq
+      end
+    end
+
+    extend InstanceMethods
+  end
+end
+
+# rubocop:enable Naming/MethodParameterName

data/lib/ecoportal/api/common/graphql/model/diffable.rb

@@ -1,28 +1,50 @@
-require 'ecoportal/api/common/graphql/model/diffable/hash_diff'
 module Ecoportal
   module API
     module Common
       module GraphQL
         class Model
           module Diffable
-            class << self
-              def included(base)
-                super
-                base.send(:include, HashDiff)
-              end
-            end
+            require_relative 'diffable/hash_diff_nesting'
+            require_relative 'diffable/classic_diff_service'
+            require_relative 'diffable/diff_service'
+
+            DIFF_CLASS = DiffService
 
             # INSTANCE METHODS
 
-            def as_update(ref = :last, ignore: [])
-              new_doc = as_json
-              ref_doc = ref == :total ? initial_doc : original_doc
+            # @note **cascaded callbacks**
+            #   1. Can **skip** rooted objects (where `root?` is `true`).
+            #     This is because nested rooted objects are usually look-ups
+            #     (not really part of the target model).
+            #   2. Allow to redefine `as_update` on each model.
+            # @param flat [Boolean] whether it should NOT perform a cascaded callback
+            #   througout all the instance objects of the model hierarchy (nested).
+            # @param ignored [Array<String>] the keys that should be ignored, not part
+            #   of the result of `as_update`
+            # @return [nil, Hash] the patch `Hash` model including only
+            #   the changes between `original_doc` and `doc`.
+            def as_update(**kargs)
+              diff_class.new(
+                self,
+                **kargs
+              ).diff
+            end
+
+            # @note `cascaded` will be more accurate in a `GraphQL` scenario.
+            # @return [Boolean] stating if there are changes.
+            def dirty?(...)
+              au = as_update(...)
+
+              return false if au.nil?
+              return false if au == {}
+
+              true
+            end
+
+            private
 
-              self.class.hash_diff(
-                new_doc,
-                ref_doc,
-                ignore: ignore
-              )
+            def diff_class
+              self.class::DIFF_CLASS
             end
           end
         end

data/lib/ecoportal/api/graphql/base/contractor_entity/member_changes.rb

@@ -0,0 +1,67 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class ContractorEntity
+          module MemberChanges
+            def associate(*values, lead: false)
+              ids = to_person_ids(*values)
+
+              associatedPeopleIds.tap do |associated|
+                associated.push!(*ids)
+                next unless lead
+
+                lead!(*ids)
+              end
+            end
+
+            def dissassociate(*values)
+              ids = to_person_ids(*values)
+
+              associatedPeopleIds.tap do |associated|
+                unlead!(*ids)
+                associated.delete!(*ids)
+              end
+            end
+
+            def lead!(*values)
+              ids = to_person_ids(*values)
+
+              leadContractorIds.tap do |leads|
+                associate(*ids)
+                leads.push!(*ids)
+              end
+            end
+
+            def unlead!(*values)
+              ids = to_person_ids(*values)
+
+              leadContractorIds.tap do |leads|
+                leads.delete!(*ids)
+              end
+            end
+
+            private
+
+            def to_person_ids(*values)
+              to_person_id(values.flatten)
+            end
+
+            def to_person_id(value)
+              case value
+              when String
+                value
+              when Ecoportal::API::V1::Person
+                value.id
+              when Hash
+                to_person_id(['id'])
+              when Enumarable
+                value.map {|val| to_person_id(val)}.compact
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/contractor_entity.rb

@@ -3,6 +3,10 @@ module Ecoportal
     class GraphQL
       module Base
         class ContractorEntity < Ecoportal::API::GraphQL::Base::Model
+          require 'ecoportal/api/graphql/base/contractor_entity/member_changes'
+
+          include MemberChanges
+
           root!
 
           passkey :id
@@ -12,7 +16,7 @@ module Ecoportal
           passthrough :schemaId
 
           passarray :associatedPeopleIds, :leadContractorIds
-          embeds_one :creator, klass: "Ecoportal::API::GraphQL::Model::User"
+          embeds_one :creator, klass: 'Ecoportal::API::GraphQL::Model::User'
         end
       end
     end

data/lib/ecoportal/api/graphql/logic/mutation.rb

@@ -28,6 +28,7 @@ module Ecoportal
             puts "Internal Error with these input ('#{input.class}'):"
             pp input
             raise
+          # rescue Graphlient::Errors::TimeoutError => _err
           end
 
           def response_class

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '0.4.7'.freeze
+    GRAPQL_VERSION = '1.1.1'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 1.1.1
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-02 00:00:00.000000000 Z
+date: 2025-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -158,20 +158,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.16
+        version: 3.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.16
+        version: 3.1.1
 - !ruby/object:Gem::Dependency
   name: graphlient
   requirement: !ruby/object:Gem::Requirement
@@ -225,7 +225,10 @@ files:
 - lib/ecoportal/api/common/graphql/model.rb
 - lib/ecoportal/api/common/graphql/model/as_input.rb
 - lib/ecoportal/api/common/graphql/model/diffable.rb
+- lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb
+- lib/ecoportal/api/common/graphql/model/diffable/diff_service.rb
 - lib/ecoportal/api/common/graphql/model/diffable/hash_diff.rb
+- lib/ecoportal/api/common/graphql/model/diffable/hash_diff_nesting.rb
 - lib/ecoportal/api/common/graphql/patches.rb
 - lib/ecoportal/api/common/graphql/query_integration.rb
 - lib/ecoportal/api/graphql.rb
@@ -233,6 +236,7 @@ files:
 - lib/ecoportal/api/graphql/base/action.rb
 - lib/ecoportal/api/graphql/base/action_category.rb
 - lib/ecoportal/api/graphql/base/contractor_entity.rb
+- lib/ecoportal/api/graphql/base/contractor_entity/member_changes.rb
 - lib/ecoportal/api/graphql/base/date_time.rb
 - lib/ecoportal/api/graphql/base/field.rb
 - lib/ecoportal/api/graphql/base/file_attachment.rb