julewire-core 1.0.0

data/lib/julewire/core/fields/field_stack.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      # @api internal
+      # Immutable layers keep snapshots stable while each stack tracks only its
+      # current head and versioned read caches.
+      class FieldStack
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        class Layer
+          attr_reader :fields, :parent
+
+          def initialize(parent, fields, delete_paths: nil, clear_parent_deletes: true)
+            @parent = parent
+            @fields = fields
+            @delete_paths = delete_paths
+            @clear_parent_deletes = clear_parent_deletes
+            @active_delete_paths_computed = false
+            @active_delete_paths = nil
+            @snapshot = nil
+            @value_cache = nil
+          end
+
+          def snapshot
+            @snapshot ||= build_snapshot
+          end
+
+          def value_for(key)
+            return @value_cache[key] if @value_cache&.key?(key)
+
+            value = if delete_paths_for_key?(key)
+                      FieldSet.value_for(snapshot, key, default: MISSING)
+                    else
+                      field_value = FieldSet.value_for(@fields, key, default: MISSING)
+                      field_value.equal?(MISSING) ? parent_value_for(key) : Fields::Internal.frozen_copy(field_value)
+                    end
+            (@value_cache ||= {})[key] = value
+          end
+
+          def active_delete_paths
+            return @active_delete_paths if @active_delete_paths_computed
+
+            @active_delete_paths = build_active_delete_paths
+            @active_delete_paths_computed = true
+            @active_delete_paths
+          end
+
+          def snapshot_cached?
+            !@snapshot.nil?
+          end
+
+          def delete_paths_for_snapshot
+            @clear_parent_deletes ? @delete_paths : active_delete_paths
+          end
+
+          private
+
+          def build_snapshot
+            return build_direct_snapshot unless @parent
+            return build_parent_snapshot if @parent.snapshot_cached?
+
+            snapshot = source_snapshot_base
+            source_chain.reverse_each do |source|
+              FieldSet.merge!(snapshot, source.fields)
+              paths = source.delete_paths_for_snapshot
+              Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
+            end
+            Fields::Internal.frozen_copy(snapshot)
+          end
+
+          def build_direct_snapshot
+            snapshot = FieldSet.merge!({}, @fields)
+            paths = delete_paths_for_snapshot
+            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
+            Fields::Internal.frozen_copy(snapshot)
+          end
+
+          def build_parent_snapshot
+            snapshot = FieldSet.merge(@parent.snapshot, @fields)
+            paths = delete_paths_for_snapshot
+            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
+            Fields::Internal.frozen_copy(snapshot)
+          end
+
+          def source_snapshot_base
+            source = source_chain_base
+            source ? FieldSet.deep_dup(source.snapshot) : {}
+          end
+
+          def source_chain
+            sources = []
+            source = self
+            until source.nil? || source.snapshot_cached?
+              sources << source
+              source = source.parent
+            end
+            sources
+          end
+
+          def source_chain_base
+            source = self
+            source = source.parent until source.nil? || source.snapshot_cached?
+            source
+          end
+
+          def parent_value_for(key)
+            return MISSING unless @parent
+
+            @parent.value_for(key)
+          end
+
+          def delete_paths_for_key?(key)
+            active_delete_paths&.any? { it.first == key }
+          end
+
+          def build_active_delete_paths
+            paths = @parent&.active_delete_paths
+            paths = clear_active_delete_paths(paths) if paths && @clear_parent_deletes && !@fields.empty?
+            paths = append_delete_paths(paths) if @delete_paths
+            return unless paths
+
+            paths.empty? ? nil : paths
+          end
+
+          def clear_active_delete_paths(paths)
+            paths = paths.dup
+            Fields::Internal.clear_delete_paths!(paths, @fields)
+            paths
+          end
+
+          def append_delete_paths(paths)
+            paths ? paths + @delete_paths : @delete_paths
+          end
+        end
+        private_constant :Layer
+
+        def initialize(fields = {}, delete_paths: false, source: nil)
+          @source = source
+          @delete_paths_enabled = delete_paths
+          @version = 0
+          @snapshot_version = nil
+          @snapshot = nil
+          @value_cache = nil
+          add(fields) if fields.is_a?(Hash) && !fields.empty?
+        end
+
+        def snapshot
+          return @snapshot if @snapshot_version == @version
+
+          @snapshot = @source ? @source.snapshot : EMPTY_HASH
+          @snapshot_version = @version
+          @snapshot
+        end
+
+        def fork
+          self.class.new(delete_paths: @delete_paths_enabled, source: @source)
+        end
+
+        def value_for(key, default:)
+          cache = @value_cache
+          return cache[key] if cache&.key?(key)
+
+          if key.is_a?(String)
+            key = Fields::Internal.normalize_key(key)
+            cache = @value_cache
+            return cache[key] if cache&.key?(key)
+          end
+
+          value = source_value_for(key)
+          return default if value.equal?(MISSING)
+
+          (@value_cache ||= {})[key] = value
+        end
+
+        def add(fields = nil, owned: false, **keyword_fields)
+          fields = field_input(fields, keyword_fields, owned: owned)
+          return unless fields.is_a?(Hash)
+          return if fields.empty?
+
+          fields = normalize_owned_keys(fields) if owned
+          @source = Layer.new(@source, fields, clear_parent_deletes: true)
+          invalidate_snapshot!
+        end
+
+        def delete(path)
+          return if path.empty?
+          return unless @delete_paths_enabled
+
+          @source = Layer.new(@source, {}, delete_paths: [path], clear_parent_deletes: false)
+          invalidate_snapshot!
+        end
+
+        def with(fields = nil, owned: false, **keyword_fields, &)
+          fields = field_input(fields, keyword_fields, owned: owned)
+          return yield unless fields.is_a?(Hash)
+          return yield if fields.empty?
+
+          fields = normalize_owned_keys(fields) if owned
+          with_layer(fields, &)
+        end
+
+        def without(path, &)
+          raise ArgumentError, "field path is required" if path.empty?
+
+          return yield unless @delete_paths_enabled
+
+          with_layer({}, delete_paths: [path], &)
+        end
+
+        private
+
+        def field_input(fields, keyword_fields, owned:)
+          if owned
+            return fields if keyword_fields.empty?
+            return keyword_fields if fields.nil?
+            return fields.merge(keyword_fields) if fields.is_a?(Hash)
+
+            return keyword_fields
+          end
+
+          return FieldSet.deep_symbolize_keys(fields) if keyword_fields.empty?
+
+          FieldSet.coerce(fields, keyword_fields)
+        end
+
+        def with_layer(fields, delete_paths: nil)
+          previous_source = @source
+          @source = Layer.new(previous_source, fields, delete_paths: delete_paths, clear_parent_deletes: false)
+          invalidate_snapshot!
+          begin
+            yield
+          ensure
+            @source = previous_source
+            invalidate_snapshot!
+          end
+        end
+
+        def normalize_owned_keys(fields)
+          return fields unless fields.any? { |key, _value| key.is_a?(String) }
+
+          fields.to_h { |key, value| [Fields::Internal.normalize_key(key), value] }
+        end
+
+        def source_value_for(key)
+          return MISSING unless @source
+
+          unless @source.parent
+            # Single-layer hits avoid Layer's delete-path/cache bookkeeping.
+            field_value = FieldSet.value_for(@source.fields, key, default: MISSING)
+            return Fields::Internal.frozen_copy(field_value) unless field_value.equal?(MISSING)
+          end
+
+          value = @source.value_for(key)
+          value.equal?(MISSING) ? MISSING : value
+        end
+
+        def invalidate_snapshot!
+          @version += 1
+          @snapshot = nil
+          @snapshot_version = nil
+          @value_cache = nil
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/fields/internal/deletion.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      module Internal
+        module Deletion
+          class << self
+            def delete_path!(target, path)
+              normalized_path = normalize_path(path)
+              return target if normalized_path.empty?
+
+              deep_delete_path!(target, normalized_path)
+              target
+            end
+
+            def apply_delete_paths!(target, paths)
+              paths.each { delete_path!(target, it) }
+              target
+            end
+
+            def clear_delete_paths!(paths, fields)
+              additions = field_paths(fields)
+              paths.reject! do |path|
+                additions.any? { path_overlap?(path, it) }
+              end
+            end
+
+            def normalize_path(path)
+              Array(path).flatten.filter_map { Internal.normalize_key(it) }
+            end
+
+            private
+
+            def field_paths(fields, prefix = [])
+              return [] unless fields.is_a?(Hash)
+
+              fields.flat_map do |key, value|
+                path = prefix + [Internal.normalize_key(key)]
+                nested = value.is_a?(Hash) ? field_paths(value, path) : []
+                nested.empty? ? [path] : nested
+              end
+            end
+
+            def path_overlap?(left, right)
+              shortest = [left.length, right.length].min
+              left.first(shortest) == right.first(shortest)
+            end
+
+            def deep_delete_path!(target, path)
+              return unless target.is_a?(Hash)
+
+              key = path.first
+              if path.one?
+                Internal.delete_key!(target, key)
+                return
+              end
+
+              child = FieldSet.value_for(target, key)
+              deep_delete_path!(child, path.drop(1))
+              Internal.delete_key!(target, key) if child.is_a?(Hash) && child.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/fields/internal.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      module Internal
+        EMPTY_ARRAY = [].freeze
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_ARRAY, :EMPTY_HASH
+
+        class << self
+          def normalize_key(key)
+            key.is_a?(String) ? key.to_sym : key
+          end
+
+          def delete_key!(target, key)
+            target.delete(normalize_key(key))
+          end
+
+          def frozen_copy(value)
+            return EMPTY_HASH if value.is_a?(Hash) && value.empty?
+            return EMPTY_ARRAY if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(value, freeze_values: true)
+          end
+
+          def deep_merge(left, right)
+            deep_merge!(FieldSet.deep_symbolize_keys(left), right)
+          end
+
+          def deep_merge!(target, fields)
+            merge_values!(target, fields) do |value, existing|
+              if existing.is_a?(Hash) && value.is_a?(Hash)
+                deep_merge!(existing, value)
+              else
+                FieldSet.deep_symbolize_keys(value)
+              end
+            end
+          end
+
+          def deep_merge_owned!(target, fields)
+            merge_values!(target, fields) do |value, existing|
+              if existing.is_a?(Hash) && value.is_a?(Hash)
+                deep_merge_owned!(existing, value)
+              else
+                value
+              end
+            end
+          end
+
+          def merge_owned!(target, fields)
+            merge_values!(target, fields) { |value, _existing| value }
+          end
+
+          def frozen_deep_symbolize_keys(value)
+            return EMPTY_HASH if value.is_a?(Hash) && value.empty?
+            return EMPTY_ARRAY if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(value, freeze_values: true, symbolize_keys: true)
+          end
+
+          def delete_path!(target, path) = Deletion.delete_path!(target, path)
+
+          def apply_delete_paths!(target, paths) = Deletion.apply_delete_paths!(target, paths)
+
+          def clear_delete_paths!(paths, fields) = Deletion.clear_delete_paths!(paths, fields)
+
+          def normalize_path(path) = Deletion.normalize_path(path)
+
+          private
+
+          def merge_values!(target, fields)
+            return target unless fields.is_a?(Hash)
+
+            fields.each do |key, value|
+              normalized_key = normalize_key(key)
+              existing = target[normalized_key]
+              target[normalized_key] = yield value, existing
+            end
+
+            target
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/fields/lookup.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      module Lookup
+        class << self
+          def value(source, key)
+            return unless source.respond_to?(:[])
+
+            direct = source[key]
+            return direct unless direct.nil?
+
+            alternate_key(source, key)
+          rescue StandardError
+            nil
+          end
+
+          def blank?(value)
+            value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          end
+
+          private
+
+          def alternate_key(source, key)
+            case key
+            when Symbol then source[key.name]
+            when String then source[key.to_sym]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/fields/section_proxy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class SectionProxy
+        STORE_METHODS = Bags.app_write_sections.to_h do |section|
+          [
+            section,
+            {
+              add: :"add_#{section}",
+              hash: :"#{section}_hash",
+              value: :"#{section}_value",
+              with: :"with_#{section}"
+            }.freeze
+          ]
+        end.freeze
+        private_constant :STORE_METHODS
+
+        def initialize(store, section)
+          @store = store
+          @section = section
+        end
+
+        def add(fields = nil, **keyword_fields)
+          add_fields(fields, keyword_fields) { add_section(it) }
+        end
+
+        def with(fields = nil, **keyword_fields, &)
+          raise ArgumentError, "block required" unless block_given?
+
+          with_fields(fields, keyword_fields) { with_section(it, &) }
+        end
+
+        def to_h = section_hash
+
+        def [](key) = nil_if_missing(section_value(key, default: MISSING))
+
+        private
+
+        def coerce_fields(fields, keyword_fields)
+          FieldSet.coerce(fields, keyword_fields, invalid: :wrap)
+        end
+
+        def add_fields(fields, keyword_fields)
+          yield coerce_fields(fields, keyword_fields)
+          self
+        end
+
+        def with_fields(fields, keyword_fields)
+          yield coerce_fields(fields, keyword_fields)
+        end
+
+        def nil_if_missing(value)
+          value.equal?(MISSING) ? nil : value
+        end
+
+        def add_section(fields)
+          call_store(:add, fields)
+        end
+
+        def with_section(fields, &)
+          call_store(:with, fields, &)
+        end
+
+        def section_hash
+          call_store(:hash)
+        end
+
+        def section_value(key, default:)
+          call_store(:value, key, default: default)
+        end
+
+        def call_store(action, ...)
+          @store.public_send(store_method(action), ...)
+        end
+
+        def store_method(action)
+          STORE_METHODS.fetch(section).fetch(action)
+        end
+
+        attr_reader :section
+      end
+
+      private_constant :SectionProxy
+    end
+  end
+end

data/lib/julewire/core/fields/stack_set.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class StackSet
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        class << self
+          def inherit_from(source, inherit_attributes: true)
+            stacks = Bags.stack_sections.to_h do |section|
+              [section, inherited_stack(source, section, inherit_section?(section, inherit_attributes))]
+            end
+            new(**stacks)
+          end
+
+          private
+
+          def inherit_section?(section, inherit_attributes)
+            inherit_attributes || !%i[attributes neutral].include?(section)
+          end
+
+          def inherited_stack(source, section, inherit)
+            inherit ? source.stack(section).fork : FieldStack.new
+          end
+        end
+
+        def initialize(**sections)
+          @stacks = Bags.stack_sections.to_h do |section|
+            [section, field_stack(sections.fetch(section, EMPTY_HASH), section)]
+          end.freeze
+        end
+
+        def stack(section)
+          @stacks.fetch(section)
+        end
+
+        def snapshot(section)
+          stack(section).snapshot
+        end
+
+        def add(section, fields, owned: false)
+          stack(section).add(fields, owned: owned)
+        end
+
+        def delete(section, path)
+          stack(section).delete(path)
+        end
+
+        def with(section, fields, owned: false, &)
+          stack(section).with(fields, owned: owned, &)
+        end
+
+        def without(section, path, &)
+          stack(section).without(path, &)
+        end
+
+        private
+
+        def field_stack(value, section)
+          return value if value.is_a?(FieldStack)
+
+          FieldStack.new(value, delete_paths: Bags.delete_paths?(section))
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/fields/static_labels.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class StaticLabels
+        def initialize
+          @fields = {}
+        end
+
+        def add(fields = nil, **keyword_fields)
+          FieldSet.merge!(@fields, FieldSet.coerce(fields, keyword_fields, invalid: :raise))
+          self
+        end
+
+        def clear
+          @fields.clear
+          self
+        end
+
+        def remove(key)
+          Fields::Internal.delete_key!(@fields, key)
+          self
+        end
+
+        def to_h
+          FieldSet.deep_dup(@fields)
+        end
+
+        def copy
+          self.class.new.tap do |copy|
+            copy.add(to_h)
+          end
+        end
+
+        def freeze
+          @fields.freeze
+          super
+        end
+      end
+    end
+  end
+end