julewire-core 1.0.1 → 1.1.0

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

@@ -26,35 +26,31 @@ module Julewire
           source
         ].freeze
 
-        class << self
-          private
-
-          def define(name, **capabilities)
-            Definition.new(
-              name: name,
-              record_hash: true,
-              transform_container: true,
-              app_write: false,
-              integration_write: false,
-              propagate: false,
-              emit_by_default: true,
-              delete_paths: false,
-              stack: false,
-              **capabilities
-            )
-          end
+        definition = lambda do |name, **capabilities|
+          Definition.new(
+            name: name,
+            record_hash: true,
+            transform_container: true,
+            app_write: false,
+            integration_write: false,
+            propagate: false,
+            emit_by_default: true,
+            delete_paths: false,
+            stack: false,
+            **capabilities
+          )
         end
 
         DEFINITIONS = {
-          execution: define(:execution, integration_write: true, propagate: true),
-          context: define(
+          execution: definition.call(:execution, integration_write: true, propagate: true),
+          context: definition.call(
             :context,
             app_write: true,
             integration_write: true,
             propagate: true,
             stack: true
           ),
-          carry: define(
+          carry: definition.call(
             :carry,
             app_write: true,
             integration_write: true,
@@ -63,18 +59,18 @@ module Julewire
             delete_paths: true,
             stack: true
           ),
-          neutral: define(:neutral, integration_write: true, emit_by_default: false, stack: true),
-          attributes: define(
+          neutral: definition.call(:neutral, integration_write: true, emit_by_default: false, stack: true),
+          attributes: definition.call(
             :attributes,
             app_write: true,
             integration_write: true,
             stack: true
           ),
-          labels: define(:labels),
-          payload: define(:payload),
-          metrics: define(:metrics),
-          error: define(:error, record_hash: false),
-          summary: define(
+          labels: definition.call(:labels),
+          payload: definition.call(:payload),
+          metrics: definition.call(:metrics),
+          error: definition.call(:error, record_hash: false),
+          summary: definition.call(
             :summary,
             record_hash: false,
             transform_container: false,

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

@@ -5,16 +5,22 @@ module Julewire
     module Fields
       # @api integration_spi
       module FieldSet
+        Serializer = Serialization::Serializer
+        TRUNCATION_METADATA_KEY = Serializer::TRUNCATION_METADATA_KEY.to_sym
+        RESERVED_TRUNCATION_METADATA_ERROR =
+          "#{Serializer::TRUNCATION_METADATA_KEY} is reserved for Julewire truncation metadata".freeze
+        INVALID_MODES = %i[ignore raise wrap].freeze
         VALUE_KEY = :value
+        private_constant :Serializer, :TRUNCATION_METADATA_KEY, :RESERVED_TRUNCATION_METADATA_ERROR, :INVALID_MODES
 
         class << self
           # Public ingress accepts String or Symbol keys. Core stores Symbol keys
           # after normalization so extension contracts stay simple.
-          def coerce(fields = nil, keyword_fields = {}, invalid: :ignore)
+          def coerce(fields = nil, keyword_fields = nil, invalid: :ignore)
+            validate_invalid_mode!(invalid)
             coerced = {}
             coerce_fields!(coerced, fields, invalid: invalid) unless fields.nil?
-            merge!(coerced, keyword_fields) unless keyword_fields.empty?
-            coerced
+            merge!(coerced, keyword_fields)
           end
 
           def merge(left, right)
@@ -25,7 +31,7 @@ module Julewire
             return target unless fields.is_a?(Hash)
 
             fields.each do |key, value|
-              target[Fields::Internal.normalize_key(key)] = copy_field_value(value)
+              target[normalized_field_key(key)] = copy_field_value(value)
             end
 
             target
@@ -48,24 +54,18 @@ module Julewire
           end
 
           def frozen_copy(value)
-            Fields::Internal.frozen_copy(value)
+            Internal.frozen_copy(value)
           end
 
           def value_for(hash, key, default: nil)
             return default unless hash.is_a?(Hash)
 
-            normalized = key.is_a?(String) ? Fields::Internal.normalize_key(key) : key
-            return hash[normalized] if hash.key?(normalized)
-
-            default
+            hash.fetch(Internal.normalize_key(key), default)
           end
 
           private
 
           def deep_dup_with(value, preserve_truncation_metadata:)
-            return {} if value.is_a?(Hash) && value.empty?
-            return [] if value.is_a?(Array) && value.empty?
-
             Serialization::ValueCopy.call(
               value,
               preserve_truncation_metadata: preserve_truncation_metadata
@@ -73,14 +73,11 @@ module Julewire
           end
 
           def deep_symbolize_keys_with(value, preserve_truncation_metadata:)
-            return {} if value.is_a?(Hash) && value.empty?
-            return [] if value.is_a?(Array) && value.empty?
-
             Serialization::ValueCopy.call(
               value,
-              max_array_items: Serialization::Serializer::DEFAULT_MAX_ARRAY_ITEMS,
-              max_hash_keys: Serialization::Serializer::DEFAULT_MAX_HASH_KEYS,
-              max_string_bytes: Serialization::Serializer::DEFAULT_MAX_STRING_BYTES,
+              max_array_items: Serializer::DEFAULT_MAX_ARRAY_ITEMS,
+              max_hash_keys: Serializer::DEFAULT_MAX_HASH_KEYS,
+              max_string_bytes: Serializer::DEFAULT_MAX_STRING_BYTES,
               preserve_truncation_metadata: preserve_truncation_metadata,
               symbolize_keys: true
             )
@@ -90,12 +87,25 @@ module Julewire
             if fields.is_a?(Hash)
               merge!(target, fields)
             elsif invalid == :wrap
-              target[VALUE_KEY] = deep_dup(fields)
+              target[VALUE_KEY] = copy_field_value(fields)
             elsif invalid == :raise
               raise ArgumentError, "fields must be a Hash"
             end
           end
 
+          def validate_invalid_mode!(invalid)
+            return if INVALID_MODES.include?(invalid)
+
+            raise ArgumentError, "invalid field coercion mode: #{invalid.inspect}"
+          end
+
+          def normalized_field_key(key)
+            normalized_key = Internal.normalize_key(key)
+            raise ArgumentError, RESERVED_TRUNCATION_METADATA_ERROR if normalized_key == TRUNCATION_METADATA_KEY
+
+            normalized_key
+          end
+
           def copy_field_value(value) = deep_symbolize_keys(value)
         end
       end

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

@@ -4,8 +4,8 @@ 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.
+      # Immutable layers keep snapshots stable while each stack tracks only the
+      # current head and snapshot cache.
       class FieldStack
         EMPTY_HASH = {}.freeze
         private_constant :EMPTY_HASH
@@ -13,26 +13,37 @@ module Julewire
         class Layer
           attr_reader :fields, :parent
 
-          def initialize(parent, fields, delete_paths: nil, clear_parent_deletes: true, owned: false)
+          class << self
+            def fields(parent, fields, clear_parent_deletes: true)
+              clear_parent_fields = fields if clear_parent_deletes
+              new(
+                parent,
+                fields,
+                delete_paths: nil,
+                clear_parent_fields:
+              )
+            end
+
+            def delete_paths(parent, paths)
+              new(parent, nil, delete_paths: paths, clear_parent_fields: nil)
+            end
+
+            private :new
+          end
+
+          def initialize(parent, fields, delete_paths:, clear_parent_fields:)
             @parent = parent
             @fields = fields
             @delete_paths = delete_paths
-            @clear_parent_deletes = clear_parent_deletes
-            @owned = owned
-            @active_delete_paths_computed = false
-            @active_delete_paths = nil
-            @snapshot = nil
-            @value_cache = nil
+            @clear_parent_fields = clear_parent_fields
           end
 
-          def owned? = @owned
-
           def snapshot
             @snapshot ||= build_snapshot
           end
 
           def value_for(key)
-            return @value_cache[key] if @value_cache&.key?(key)
+            return @value_cache.fetch(key) if @value_cache&.key?(key)
 
             value = if delete_paths_for_key?(key)
                       FieldSet.value_for(snapshot, key, default: MISSING)
@@ -44,82 +55,42 @@ module Julewire
           end
 
           def active_delete_paths
-            return @active_delete_paths if @active_delete_paths_computed
+            return @active_delete_paths if instance_variable_defined?(:@active_delete_paths)
 
             @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
-
           def merge_into(snapshot)
-            if @owned
-              Fields::Internal.merge_owned!(snapshot, FieldSet.deep_symbolize_owned_keys(@fields))
-            else
-              FieldSet.merge!(snapshot, @fields)
-            end
+            Internal.merge_owned!(snapshot, FieldSet.deep_dup_owned(@fields))
           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|
-              source.merge_into(snapshot)
-              paths = source.delete_paths_for_snapshot
-              Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            end
-            Fields::Internal.frozen_owned_copy(snapshot)
-          end
-
-          def build_direct_snapshot
-            snapshot = merge_into({})
-            paths = delete_paths_for_snapshot
-            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            Fields::Internal.frozen_owned_copy(snapshot)
-          end
-
-          def build_parent_snapshot
-            snapshot = FieldSet.deep_dup_owned(@parent.snapshot)
-            merge_into(snapshot)
-            paths = delete_paths_for_snapshot
-            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            Fields::Internal.frozen_owned_copy(snapshot)
-          end
-
-          def source_snapshot_base
-            source = source_chain_base
-            source ? FieldSet.deep_dup_owned(source.snapshot) : {}
+            sources, base = source_layers_and_base
+            snapshot = base ? FieldSet.deep_dup_owned(base.snapshot) : {}
+            sources.reverse_each { it.merge_into(snapshot) }
+            paths = active_delete_paths
+            Internal.apply_delete_paths!(snapshot, paths) if paths
+            Internal.frozen_owned_copy(snapshot)
           end
 
           def frozen_field_value(value)
-            @owned ? Fields::Internal.frozen_owned_copy(value) : Fields::Internal.frozen_copy(value)
+            Internal.frozen_owned_copy(value)
           end
 
-          def source_chain
-            sources = []
-            source = self
-            until source.nil? || source.snapshot_cached?
-              sources << source
-              source = source.parent
-            end
-            sources
-          end
+          def source_layers_and_base(source = self, seen_sources = [], sources = [])
+            return [sources, source] if source.nil? || source.snapshot_cached?
+
+            raise Error, "field stack layer cycle" if seen_sources.include?(source)
 
-          def source_chain_base
-            source = self
-            source = source.parent until source.nil? || source.snapshot_cached?
-            source
+            seen_sources << source
+            sources << source
+            source_layers_and_base(source.parent, seen_sources, sources)
           end
 
           def parent_value_for(key)
@@ -134,16 +105,14 @@ module Julewire
 
           def build_active_delete_paths
             paths = @parent&.active_delete_paths
-            paths = clear_active_delete_paths(paths) if paths && @clear_parent_deletes && !@fields.empty?
+            paths = clear_active_delete_paths(paths) if paths
             paths = append_delete_paths(paths) if @delete_paths
-            return unless paths
-
-            paths.empty? ? nil : paths
+            paths
           end
 
           def clear_active_delete_paths(paths)
             paths = paths.dup
-            Fields::Internal.clear_delete_paths!(paths, @fields)
+            Internal.clear_delete_paths!(paths, @clear_parent_fields)
             paths
           end
 
@@ -153,51 +122,35 @@ module Julewire
         end
         private_constant :Layer
 
-        def initialize(fields = {}, delete_paths: false, source: nil)
+        def initialize(fields = nil, 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?
+          add(fields)
         end
 
         def snapshot
-          return @snapshot if @snapshot_version == @version
+          return @snapshot if @snapshot
 
           @snapshot = @source ? @source.snapshot : EMPTY_HASH
-          @snapshot_version = @version
-          @snapshot
         end
 
-        def fork
+        def branch
           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
-
+          key = Internal.normalize_key(key)
           value = source_value_for(key)
           return default if value.equal?(MISSING)
 
-          (@value_cache ||= {})[key] = value
+          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, owned: owned)
+          @source = Layer.fields(@source, fields)
           invalidate_snapshot!
         end
 
@@ -205,17 +158,15 @@ module Julewire
           return if path.empty?
           return unless @delete_paths_enabled
 
-          @source = Layer.new(@source, {}, delete_paths: [path], clear_parent_deletes: false)
+          @source = Layer.delete_paths(@source, [path])
           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, owned: owned, &)
+          with_layer(fields, &)
         end
 
         def without(path, &)
@@ -223,34 +174,25 @@ module Julewire
 
           return yield unless @delete_paths_enabled
 
-          with_layer({}, delete_paths: [path], &)
+          with_delete_layer([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)
+            fields = keyword_fields if fields.nil?
+            Serialization::DeepFreeze.validate_symbol_hash(fields)
 
-            return keyword_fields
+            return fields.merge(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, owned: false)
+        def with_layer(fields)
           previous_source = @source
-          @source = Layer.new(
-            previous_source,
-            fields,
-            delete_paths: delete_paths,
-            clear_parent_deletes: false,
-            owned: owned
-          )
+          @source = Layer.fields(previous_source, fields, clear_parent_deletes: false)
           invalidate_snapshot!
           begin
             yield
@@ -260,34 +202,26 @@ module Julewire
           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] }
+        def with_delete_layer(delete_paths)
+          previous_source = @source
+          @source = Layer.delete_paths(previous_source, delete_paths)
+          invalidate_snapshot!
+          begin
+            yield
+          ensure
+            @source = previous_source
+            invalidate_snapshot!
+          end
         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 frozen_source_value(field_value, @source.owned?) unless field_value.equal?(MISSING)
-          end
-
-          value = @source.value_for(key)
-          value.equal?(MISSING) ? MISSING : value
-        end
-
-        def frozen_source_value(value, owned)
-          owned ? Fields::Internal.frozen_owned_copy(value) : Fields::Internal.frozen_copy(value)
+          @source.value_for(key)
         end
 
         def invalidate_snapshot!
-          @version += 1
           @snapshot = nil
-          @snapshot_version = nil
-          @value_cache = nil
         end
       end
     end

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

@@ -11,12 +11,10 @@ module Julewire
               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)
@@ -27,7 +25,7 @@ module Julewire
             end
 
             def normalize_path(path)
-              Array(path).flatten.filter_map { Internal.normalize_key(it) }
+              Array(path).flatten.map { Internal.normalize_key(it) }
             end
 
             private
@@ -37,7 +35,7 @@ module Julewire
 
               fields.flat_map do |key, value|
                 path = prefix + [Internal.normalize_key(key)]
-                nested = value.is_a?(Hash) ? field_paths(value, path) : []
+                nested = field_paths(value, path)
                 nested.empty? ? [path] : nested
               end
             end
@@ -53,12 +51,11 @@ module Julewire
               key = path.first
               if path.one?
                 Internal.delete_key!(target, key)
-                return
+              else
+                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
-
-              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

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

@@ -4,13 +4,16 @@ module Julewire
   module Core
     module Fields
       module Internal
-        EMPTY_ARRAY = [].freeze
-        EMPTY_HASH = {}.freeze
-        private_constant :EMPTY_ARRAY, :EMPTY_HASH
+        FIELD_KEY_ERROR = "field keys must be String or Symbol"
+        RECORD_STRING_KEY_ERROR = "record must not use string keys"
+        RECORD_SYMBOL_KEY_ERROR = "record keys must be Symbols"
 
         class << self
           def normalize_key(key)
-            key.is_a?(String) ? key.to_sym : key
+            return key.to_sym if key.is_a?(String)
+            return key if key.instance_of?(Symbol)
+
+            raise TypeError, FIELD_KEY_ERROR
           end
 
           def delete_key!(target, key)
@@ -25,26 +28,12 @@ module Julewire
             frozen_copy_with(value, preserve_truncation_metadata: true)
           end
 
-          def frozen_deep_symbolize_keys(value)
-            frozen_deep_symbolize_keys_with(value, preserve_truncation_metadata: false)
-          end
-
-          def frozen_deep_symbolize_owned_keys(value)
-            frozen_deep_symbolize_keys_with(value, preserve_truncation_metadata: 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)
 
-          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)
@@ -56,7 +45,7 @@ module Julewire
           end
 
           def deep_merge_owned!(target, fields)
-            merge_values!(target, fields) do |value, existing|
+            merge_owned_values!(target, fields) do |value, existing|
               if existing.is_a?(Hash) && value.is_a?(Hash)
                 deep_merge_owned!(existing, value)
               else
@@ -66,15 +55,12 @@ module Julewire
           end
 
           def merge_owned!(target, fields)
-            merge_values!(target, fields) { |value, _existing| value }
+            merge_owned_values!(target, fields) { |value, _existing| value }
           end
 
           private
 
           def frozen_copy_with(value, preserve_truncation_metadata:)
-            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,
@@ -82,21 +68,6 @@ module Julewire
             )
           end
 
-          def frozen_deep_symbolize_keys_with(value, preserve_truncation_metadata:)
-            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,
-              max_array_items: Serialization::Serializer::DEFAULT_MAX_ARRAY_ITEMS,
-              max_hash_keys: Serialization::Serializer::DEFAULT_MAX_HASH_KEYS,
-              max_string_bytes: Serialization::Serializer::DEFAULT_MAX_STRING_BYTES,
-              preserve_truncation_metadata: preserve_truncation_metadata,
-              symbolize_keys: true
-            )
-          end
-
           def merge_values!(target, fields)
             return target unless fields.is_a?(Hash)
 
@@ -108,6 +79,16 @@ module Julewire
 
             target
           end
+
+          def merge_owned_values!(target, fields)
+            return target unless fields.is_a?(Hash)
+
+            fields.each do |key, value|
+              target[key] = yield value, target[key]
+            end
+
+            target
+          end
         end
       end
     end