ecoportal-api-graphql 1.3.17 → 2.0.0

data/lib/ecoportal/api/common/graphql/model/CLAUDE.md

@@ -0,0 +1,28 @@
+# common/graphql/model
+
+Concerns that add dirty-tracking diff (`Diffable`) and mutation-input serialisation (`AsInput`) to the base `Common::GraphQL::Model`.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `diffable.rb` / `Model::Diffable` | Provides `as_update` (returns changed-field hash or nil) and `dirty?`; delegates to `DIFF_CLASS` (defaults to `DiffService`) |
+| `as_input.rb` / `Model::AsInput` | Instance `as_input` (wraps diff as mutation variables) + class-level `as_input(hash)` (key-sym + nil-id cleanup) |
+| `diffable/diff_service.rb` / `DiffService` | Primary diff engine: flat classic diff then cascaded reduce over nested `GraphQL::Model` children |
+| `diffable/classic_diff_service.rb` / `ClassicDiffService` | Low-level diff: compares `curr_doc` vs `prev_doc`, returns `{ id:, changed_field: new_value }` or nil |
+| `diffable/hash_diff.rb` / `HashDiff` | Primitive equality helpers used by `ClassicDiffService` |
+| `diffable/hash_diff_nesting.rb` / `HashDiffNesting` | Nested path helpers: `dig_set!`, `dig_delete!`, `dig_path?` used when building cascaded diff results |
+
+## Conventions
+
+- `DIFF_CLASS = DiffService` is a constant on `Diffable` — subclasses can override it to swap diff strategies.
+- `DiffService` `flat: true` produces a single-level diff (current model only); `flat: false` (default) recurses via `cascaded_reduce` through nested `GraphQL::Model` objects.
+- Objects declared with `root!` in their class are skipped during cascaded diff — they are independent server entities (look-ups only).
+- `as_input` on a model calls `as_update` first; returns `nil` when nothing has changed so callers can skip the mutation.
+- `as_input(target_class:)` is the preferred path when a corresponding `Input::X` class exists — delegates to `target_class.from_model(self)`.
+
+## Related
+
+- `../hash_helpers.rb` — `HashHelpers` used inside `DiffService` for key transforms
+- `../../graphql/logic/input.rb` — `Logic::Input.from_model` is the canonical consumer of `as_update`
+- `../../graphql/logic/base_model.rb` — all concrete models inherit this chain

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

@@ -1,54 +1,54 @@
-module Ecoportal
-  module API
-    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
-            end
-
-            module ClassMethods
-              def as_input(hash, clientMutationId: '')
-                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
-                  keys_to_sym_deep(hash)
-
-                hash_input.merge!(clientMutationId: clientMutationId)
-
-                Ecoportal::API::Common::GraphQL::HashHelpers.
-                  remove_nil_keys_deep(hash_input, target: :id)
-              end
-            end
-
-            # INSTANCE METHODS
-
-            def as_input(target_class: nil, clientMutationId: '')
-              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
-
-              diff = as_update
-              return nil if diff.nil?
-
-              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
-              self.class.as_input(diff, clientMutationId: clientMutationId)
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    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
+            end
+
+            module ClassMethods
+              def as_input(hash, clientMutationId: '')
+                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
+                  keys_to_sym_deep(hash)
+
+                hash_input.merge!(clientMutationId: clientMutationId)
+
+                Ecoportal::API::Common::GraphQL::HashHelpers.
+                  remove_nil_keys_deep(hash_input, target: :id)
+              end
+            end
+
+            # INSTANCE METHODS
+
+            def as_input(target_class: nil, clientMutationId: '')
+              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
+
+              diff = as_update
+              return nil if diff.nil?
+
+              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
+              self.class.as_input(diff, clientMutationId: clientMutationId)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,49 +1,49 @@
-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)
-      return target.original_doc if target.respond_to?(:original_doc)
-
-      raise "Can't fetch original underlying model for instance of #{target.class}."
-    rescue NoMethodError
-      nil
-    end
-  end
-end
+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)
+      return target.original_doc if target.respond_to?(:original_doc)
+
+      raise "Can't fetch original underlying model for instance of #{target.class}."
+    rescue NoMethodError
+      nil
+    end
+  end
+end

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

@@ -1,188 +1,188 @@
-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
-
-    # Override: GraphQL mutations expect flat changed-prop values, not patch-op wrappers.
-    # Returns { id: ..., changed_field: new_value, ... } or nil when nothing changed.
-    def classic_diff(flat: flat?, ignore: [])
-      curr = keys_to_sym_deep(curr_doc(flat: flat) || {})
-      prev = keys_to_sym_deep(prev_doc(flat: flat) || {})
-
-      data = change_data(curr, prev, ignore: to_a(ignored, ignore))
-      return nil if data == NO_CHANGES
-
-      id = get_id(curr, exception: false)
-      id ? { id: id }.merge(data) : data
-    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?
-        next result if obj == subject
-
-        sym_path = key_path.map(&:to_sym)
-
-        # Remove any flat-diff placeholder for this key before deciding its fate.
-        dig_delete!(result, sym_path) if result && dig_path?(result, sym_path)
-
-        # Discard root-class objects — they are independent entities, not mutation payload.
-        next result if root?(obj)
-        # Only cascade-diff GraphQL model objects; ecoportal-api-v2 DoubleModel
-        # subclasses (ArrayModel, etc.) have a different as_update signature.
-        next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)
-
-        value = obj.as_update(ignore: ignore)
-        next result if value.nil?
-
-        result      ||= {}
-        result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
-        dig_set!(result, sym_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)
-      # root? is a CLASS method (via Rootable::ClassMethods). The instance root?
-      # is protected and checks parent position, not the class declaration.
-      # Check the ancestor chain for any class that declared root!.
-      obj.class.ancestors.any? { |k| k.respond_to?(:root?) && k.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.class.respond_to?(:_cascaded_doc_keys)
-      return json if (excluded = subject.class._cascaded_doc_keys).empty?
-
-      except_keys(json, *excluded)
-    end
-  end
-end
+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
+
+    # Override: GraphQL mutations expect flat changed-prop values, not patch-op wrappers.
+    # Returns { id: ..., changed_field: new_value, ... } or nil when nothing changed.
+    def classic_diff(flat: flat?, ignore: [])
+      curr = keys_to_sym_deep(curr_doc(flat: flat) || {})
+      prev = keys_to_sym_deep(prev_doc(flat: flat) || {})
+
+      data = change_data(curr, prev, ignore: to_a(ignored, ignore))
+      return nil if data == NO_CHANGES
+
+      id = get_id(curr, exception: false)
+      id ? { id: id }.merge(data) : data
+    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?
+        next result if obj == subject
+
+        sym_path = key_path.map(&:to_sym)
+
+        # Remove any flat-diff placeholder for this key before deciding its fate.
+        dig_delete!(result, sym_path) if result && dig_path?(result, sym_path)
+
+        # Discard root-class objects — they are independent entities, not mutation payload.
+        next result if root?(obj)
+        # Only cascade-diff GraphQL model objects; ecoportal-api-v2 DoubleModel
+        # subclasses (ArrayModel, etc.) have a different as_update signature.
+        next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)
+
+        value = obj.as_update(ignore: ignore)
+        next result if value.nil?
+
+        result      ||= {}
+        result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
+        dig_set!(result, sym_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)
+      # root? is a CLASS method (via Rootable::ClassMethods). The instance root?
+      # is protected and checks parent position, not the class declaration.
+      # Check the ancestor chain for any class that declared root!.
+      obj.class.ancestors.any? { |k| k.respond_to?(:root?) && k.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.class.respond_to?(:_cascaded_doc_keys)
+      return json if (excluded = subject.class._cascaded_doc_keys).empty?
+
+      except_keys(json, *excluded)
+    end
+  end
+end