lutaml-model 0.8.34 → 0.8.36

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65361e31ef80bfd3600c0bc3ea4241c2b9a9e9d227b1772b9bd23f3324e92ad7
-  data.tar.gz: da258d5127e14511cd77bd1ca44e6ad1647aaaf445cc14a92102096f180a82a3
+  metadata.gz: 13023a5add888c4affa15d1e7c025548e329b0aad8112582550be7cff794524a
+  data.tar.gz: 7393786a16da4f06d7962f7395edab78b5985ab1820c98da8b95f66f669be99d
 SHA512:
-  metadata.gz: 2d5ece44cac496100e30c2d4f3c5ca3934f656bd81352ee9215e57c2a4b8563f0a7a8ae3c155909eaf132efcce992e1954731b89cd79808fcf8c948555b06abd
-  data.tar.gz: 9db5fc0ac630ad33336250d06a953357d8a2d60bb0f0cae037d5a2d9d6cc12da2fca2937aa5b73c5b490852381995937fad226049e51fd167906e900084fa837
+  metadata.gz: 03be6773d23935e26c6593d2c966f5063af4840142f988c6db534517b26b7889adc15c11c5d5280b181b9b19e35a971bbbc889ce673d63a750385e5b392d60b7
+  data.tar.gz: 656f73aab6fe55e9dbe8337a8c6ec76fae5c2cadfade74bdd30500d3ea16105cdf3de1ebce9d837b4ddd3c6851e84ac7b5b7a7f40f2729d79827014e9d0a0b9e

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--tag ~benchmark

data/lib/lutaml/model/attribute.rb

@@ -52,11 +52,13 @@ module Lutaml
         # Public reader for compiled rule plans: does this type class carry a
         # custom from_xml/from_json (answer static, probed once)?
         def custom_from_probe?(type)
-          TypeProbeCache.cache[type] ||= begin
-            base = Lutaml::Model::Type::Value.singleton_class
+          cache = TypeProbeCache.cache
+          return cache[type] if cache.key?(type)
+
+          base = Lutaml::Model::Type::Value.singleton_class
+          cache[type] =
             type.method(:from_xml).owner != base ||
-              type.method(:from_json).owner != base
-          end
+            type.method(:from_json).owner != base
         end
       end
 
@@ -434,18 +436,31 @@ module Lutaml
       end
 
       def cast_element(value, register)
-        # Resolve first: an undeclared type has to raise UnknownTypeError even
-        # when the value carries nothing, the way it did before the guard
-        # below existed.
-        resolved_type = type(register)
+        # Resolve first: an undeclared type has to raise UnknownTypeError
+        # even for a nil value (the 0.8.33 behavior).
+        type(register)
 
-        # Casting is for data. Every built-in type already hands nil and the
-        # uninitialized sentinel straight back, so this changes nothing for
-        # them. A type with its own `self.cast` returns a real instance
-        # instead, and that instance becomes a value nobody wrote — a phantom
-        # element in the document, or a one-item collection the source never
-        # contained. `cast` below guards the format entry point the same way.
-        return value if no_data?(value)
+        return value if Utils.uninitialized?(value)
+
+        # nil reaches the type's cast — the long-shipped contract
+        # ST_OnOff-style types depend on (absent attribute -> cast(nil)
+        # -> false; lutaml-model#795). What nil must NOT do is
+        # manufacture a typed INSTANCE from nothing: that is the
+        # phantom #793 removed, suppressed by the post-check below.
+        if value.nil?
+          result = cast_element_present(value, register)
+          return result if result.nil?
+          return nil if result.is_a?(Lutaml::Model::Type::Value) ||
+            result.is_a?(Lutaml::Model::Serialize)
+
+          return result
+        end
+
+        cast_element_present(value, register)
+      end
+
+      def cast_element_present(value, register)
+        resolved_type = type(register)
 
         return cast_union(value, nil, register) if union?
         return resolved_type.new(value) if value.is_a?(::Hash) && !hash_type?
@@ -783,14 +798,25 @@ instance_object = nil)
       end
 
       def cast(value, format, register, options = {})
-        # Same rule as cast_element, for the format entry point. from_json /
-        # from_yaml / from_toml / from_hash reach a missing key as nil, and a
-        # type with its own `self.cast` turns that nil into an instance the
-        # document never carried. Unlike cast_element this returns before
-        # resolving the type: resolution here depends on the format options
-        # below, and an undeclared type still raises through cast_element.
-        return value if no_data?(value)
+        # Sentinel: never a cast input. nil flows on — absent values
+        # reach the type's cast (ST_OnOff booleans, #795); a cast that
+        # manufactures a typed instance from nothing is the phantom
+        # #793 removed, suppressed here as in cast_element.
+        return value if Utils.uninitialized?(value)
+
+        if value.nil?
+          result = cast_present(value, format, register, options)
+          return result if result.nil?
+          return nil if result.is_a?(Lutaml::Model::Type::Value) ||
+            result.is_a?(Lutaml::Model::Serialize)
+
+          return result
+        end
+
+        cast_present(value, format, register, options)
+      end
 
+      def cast_present(value, format, register, options = {})
         # Namespace-aware type resolution: use type_with_namespace if namespace_uri provided
         namespace_uri = options[:namespace_uri]
         resolved_type = if options[:resolved_type]

data/lib/lutaml/model/register.rb

@@ -80,15 +80,22 @@ module Lutaml
       # @param parent_register [Symbol, String, nil] The parent's register/context ID
       # @return [Symbol, nil] The register ID to use for the child
       def self.resolve_for_child(child_class, parent_register)
-        cache_key = [child_class.object_id, parent_register]
-
         if Lutaml::Model.opal?
-          return RESOLVE_CACHE[cache_key] if RESOLVE_CACHE.key?(cache_key)
+          per_class = RESOLVE_CACHE[child_class] # rubocop:todo Style/IdenticalConditionalBranches
+          return per_class[parent_register] if per_class&.key?(parent_register)
 
-          RESOLVE_CACHE[cache_key] =
+          (RESOLVE_CACHE[child_class] ||= {})[parent_register] =
             _resolve_for_child_uncached(child_class, parent_register)
         else
-          RESOLVE_CACHE.compute_if_absent(cache_key) do
+          # Nested maps: class → register → result. Every hop keys on a
+          # stable object (Class / Symbol), so the hot lookup allocates
+          # nothing — the flat [object_id, register] array key cost one
+          # Array per call, six per parsed element.
+          per_class = RESOLVE_CACHE[child_class] # rubocop:todo Style/IdenticalConditionalBranches
+          per_class ||= RESOLVE_CACHE.compute_if_absent(child_class) do
+            Concurrent::Map.new
+          end
+          per_class.compute_if_absent(parent_register) do
             _resolve_for_child_uncached(child_class, parent_register)
           end
         end

data/lib/lutaml/model/transformation_registry.rb

@@ -174,25 +174,31 @@ module Lutaml
       # @param register [Symbol, Register, nil] The register
       # @return [Mapping] The resolved mapping
       def get_or_build_mapping(model_class, format, register)
-        # Performance: Use fast array key instead of symbol construction
+        # Performance: nested class → format → register maps keyed on
+        # stable objects; the flat array key allocated per call.
         register_id = extract_register_id(register)
-        key = [model_class.object_id, format, register_id]
 
-        # Fast path: native Ruby uses Concurrent::Map, Opal uses Hash.
-        cached = @mappings[key]
+        per_class = @mappings[model_class]
+        per_format = per_class&.[](format)
+        cached = per_format&.[](register_id)
         return cached if cached
 
-        # Build mapping OUTSIDE any lock to avoid deadlock
-        # (ensure_mappings_imported! may recursively call get_or_build_mapping)
         mapping = model_class.mappings[format]
         mapping = mapping || model_class.default_mappings(format)
 
         mapping.ensure_mappings_imported!(register_id)
 
-        @mappings[key] = mapping
+        per_class = (@mappings[model_class] ||= new_inner_map)
+        (per_class[format] ||= new_inner_map)[register_id] = mapping
         mapping
       end
 
+      # Inner cache level container matching the outer map's engine
+      # (Concurrent::Map under GVL-threaded MRI, plain Hash under Opal).
+      def new_inner_map
+        Lutaml::Model.opal? ? {} : ::Concurrent::Map.new
+      end
+
       # Clear all cached data (transformations and mappings).
       #
       # This is useful for testing or when configuration changes dynamically.

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.34"
+    VERSION = "0.8.36"
   end
 end

data/lib/lutaml/xml/adapter_element.rb

@@ -64,8 +64,8 @@ module Lutaml
         name = adapter_class.name_of(node)
         super(
           node,
-          Hash(attributes),
-          Array(children),
+          attributes || NO_ATTRIBUTES,
+          children || NO_CHILDREN,
           text,
           name: name,
           parent_document: parent,
@@ -146,8 +146,19 @@ module Lutaml
         end
       end
 
+      # Shared frozen empties: the parse path hands these straight into
+      # XmlElement (which never mutates the containers it is given), so
+      # attribute-less elements — the majority in real documents — build
+      # nothing here.
+      NO_ATTRIBUTES = {}.freeze # rubocop:todo Lint/UselessConstantScoping
+      NO_CHILDREN = [].freeze # rubocop:todo Lint/UselessConstantScoping
+      EMPTY_ATTRIBUTES = [{}, nil].freeze # rubocop:todo Lint/UselessConstantScoping
+
       def node_attributes_with_order(node)
-        return [{}, nil] unless node.is_a?(Moxml::Element)
+        return EMPTY_ATTRIBUTES unless node.is_a?(Moxml::Element)
+
+        attrs = node.attributes
+        return EMPTY_ATTRIBUTES if attrs.respond_to?(:empty?) && attrs.empty?
 
         order = []
         hash = node.attributes.each_with_object({}) do |attr, h|
@@ -174,7 +185,7 @@ module Lutaml
       end
 
       def parse_children(node, default_namespace: nil)
-        return [] unless node.children
+        return NO_CHILDREN unless node.children
 
         # Non-element children (text/cdata/comment/PI) stay RAW moxml
         # nodes in the list — the hot scalar parse path reads text off
@@ -197,6 +208,8 @@ module Lutaml
       public
 
       def children
+        return @children if @children.empty?
+
         unless @non_element_children_wrapped
           @children.map! do |child|
             if child.is_a?(Moxml::Node) && !child.is_a?(Moxml::Element)

data/lib/lutaml/xml/model_transform.rb

@@ -402,7 +402,7 @@ instance_is_serialize = nil)
         # dup: XmlElement#order hands back a frozen cache shared with the
         # DOM. The model's copy has to stay mutable so callers can maintain
         # element_order themselves.
-        instance.element_order = doc.root.order.dup
+        instance.element_order = doc.root.order
         if instance_is_serialize && doc.root.is_a?(::Lutaml::Xml::XmlElement)
           instance.attribute_order = doc.root.attribute_order
         end

data/spec/benchmarks/xml_parsing_benchmark_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "benchmark/ips"
+
+# Adapter-comparison benchmark, runnable on demand:
+#   bundle exec rspec --tag benchmark spec/benchmarks/
+# Tagged out of the default suite (.rsex --tag ~benchmark); asserts
+# nothing about absolute speed — machines differ — but prints i/s and
+# allocations/op so regressions are visible when run deliberately.
+RSpec.describe "XML adapter benchmark", :benchmark do
+  Item = Class.new(Lutaml::Model::Serializable) do # rubocop:todo Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    attribute :id, :integer
+    attribute :name, :string
+    attribute :tags, :string, collection: true
+
+    xml do
+      element "item"
+      map_attribute "id", to: :id
+      map_element "name", to: :name
+      map_element "tag", to: :tags
+    end
+  end
+
+  Root = Class.new(Lutaml::Model::Serializable) do # rubocop:todo Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    attribute :item, Item, collection: true
+
+    xml do
+      element "root"
+      map_element "item", to: :item
+    end
+  end
+
+  XML = +"<root>" # rubocop:todo Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  1_000.times { |i| XML << %(<item id="#{i}"><name>Item #{i}</name><tag>a</tag><tag>b</tag></item>) }
+  XML << "</root>"
+
+  def allocations_of
+    GC.start
+    before = GC.stat(:total_allocated_objects)
+    yield
+    GC.stat(:total_allocated_objects) - before
+  end
+
+  %i[nokogiri ox oga rexml leptris].each do |adapter|
+    it "#{adapter}: from_xml/to_xml i/s and allocations" do
+      model = nil
+      Lutaml::Model::Config.with_adapter(xml: adapter) do
+        begin
+          Lutaml::Model::Config.adapter_for(:xml)
+        rescue Lutaml::Model::UnknownAdapterTypeError
+          skip "#{adapter} adapter unavailable on this platform"
+        end
+        report = Benchmark.ips(time: 2, warmup: 1, quiet: true) do |x|
+          x.report("parse") { model = Root.from_xml(XML) }
+          x.report("serialize") { model.to_xml }
+        end
+        parse_ips = report.entries.first.ips
+        serialize_ips = report.entries.last.ips
+
+        allocs = allocations_of { Root.from_xml(XML) }
+        puts format( # rubocop:todo RSpec/Output
+          "%<a>-9s parse %<p>7.1f i/s  serialize %<s>7.1f i/s  %<al>8d allocs/op",
+          a: adapter, p: parse_ips, s: serialize_ips, al: allocs,
+        )
+        expect(model.item.size).to eq(1_000)
+      end
+    end
+  end
+end

data/spec/lutaml/model/absent_value_contracts_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# The 0.8.33 parse contracts restored after #795: a custom type's cast
+# sees an absent attribute's nil (ST_OnOff booleans — an absent flag is
+# semantically false), and the parsed element_order array is frozen
+# (consumers build thaw-on-demand helpers on that).
+RSpec.describe "absent-value and order contracts" do
+  before do
+    stub_const("OnOff", Class.new(Lutaml::Model::Type::Boolean) do
+      def self.cast(value, _options = {})
+        return false if value.nil?
+
+        super
+      end
+    end)
+
+    stub_const("Doc", Class.new(Lutaml::Model::Serializable) do
+      attribute :flag, OnOff
+      xml do
+        element "doc"
+        map_attribute "flag", to: :flag
+      end
+    end)
+  end
+
+  it "casts an absent attribute through the type (nil -> false)" do
+    expect(Doc.from_xml("<doc/>").flag).to be(false)
+  end
+
+  it "still casts a present attribute" do
+    expect(Doc.from_xml('<doc flag="0"/>').flag).to be(false)
+    expect(Doc.from_xml('<doc flag="1"/>').flag).to be(true)
+  end
+
+  it "hands the parsed element_order back frozen" do
+    expect(Doc.from_xml('<doc flag="1"/>').element_order).to be_frozen
+  end
+
+  it "does not manufacture typed instances from nothing" do
+    stub_const("PhantomType", Class.new(Lutaml::Model::Type::String) do
+      # Value#initialize casts what it is given, so a cast that
+      # constructs has to bypass it (see phantom_value_spec's Eager).
+      def initialize(value) # rubocop:disable Lint/MissingSuper
+        @value = value
+      end
+
+      def self.cast(value, _options = {})
+        return value if value.is_a?(PhantomType)
+
+        new("phantom(#{value.inspect})")
+      end
+    end)
+    stub_const("PhantomDoc", Class.new(Lutaml::Model::Serializable) do
+      attribute :phantom, PhantomType
+      xml do
+        element "k"
+        map_attribute "p", to: :phantom
+      end
+    end)
+
+    expect(PhantomDoc.from_xml("<k/>").phantom).to be_nil
+  end
+end

data/spec/lutaml/model/parsed_model_mutation_spec.rb

@@ -294,12 +294,18 @@ RSpec.describe "parsed model mutation" do
     end
   end
 
-  # Defect 3: element_order was frozen on parsed models.
+  # element_order on a parsed model: the parsed order array is frozen
+  # (the 0.8.33 contract consumers build thaw-on-demand helpers on,
+  # lutaml-model#795). Mutation goes through reassignment — the
+  # accessor is a public writer.
   describe "element_order on a parsed model" do
-    it "is mutable" do
+    it "is reassignable" do
       model = ParsedModelMutationSpec::Mixed.from_xml('<p><a v="1"/></p>')
 
-      expect { model.element_order << "x" }.not_to raise_error
+      expect(model.element_order).to be_frozen
+      expect do
+        model.element_order = model.element_order.dup << "x"
+      end.not_to raise_error
     end
   end
 
@@ -467,7 +473,7 @@ RSpec.describe "parsed model mutation" do
     it "serializes without raising when element_order holds an Integer" do
       model = ParsedModelMutationSpec::NilColl
         .from_xml("<s><lead>L</lead><item>a</item></s>")
-      model.element_order << 42
+      model.element_order = model.element_order.dup << 42
 
       expect { model.to_xml }.not_to raise_error
     end
@@ -475,7 +481,7 @@ RSpec.describe "parsed model mutation" do
     it "still reconciles the well-formed entries around a foreign one" do
       model = ParsedModelMutationSpec::NilColl
         .from_xml("<s><lead>L</lead><item>a</item></s>")
-      model.element_order.insert(1, 42)
+      model.element_order = model.element_order.dup.insert(1, 42)
       model.items << "b"
 
       xml = model.to_xml

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.34
+  version: 0.8.36
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -971,6 +971,7 @@ files:
 - sig/lutaml/model.rbs
 - spec/address_person_spec.rb
 - spec/address_spec.rb
+- spec/benchmarks/xml_parsing_benchmark_spec.rb
 - spec/ceramic_spec.rb
 - spec/fixtures/address.rb
 - spec/fixtures/ceramic.rb
@@ -1684,6 +1685,7 @@ files:
 - spec/lutaml/key_value/transformation/rule_compiler_spec.rb
 - spec/lutaml/key_value/transformation/value_serializer_spec.rb
 - spec/lutaml/key_value/transformation_spec.rb
+- spec/lutaml/model/absent_value_contracts_spec.rb
 - spec/lutaml/model/attribute_apply_value_map_spec.rb
 - spec/lutaml/model/attribute_collection_spec.rb
 - spec/lutaml/model/attribute_default_cache_spec.rb