lutaml-model 0.8.23 → 0.8.24

data/lib/lutaml/model/adapter_resolver.rb

@@ -286,7 +286,7 @@ module Lutaml
           if format == :toml && type_name == :tomlib && RuntimeCompatibility.windows?
             raise ArgumentError,
                   "The `:tomlib` adapter is not supported on Windows due to " \
-                  "segmentation fault issues. Please use `:toml_rb` instead."
+                  "segmentation fault issues. Please use `:teptris` or `:toml_rb` instead."
           end
 
           available = adapter_config[:available]
@@ -363,11 +363,23 @@ module Lutaml
             detect_xml_adapter
           when :toml
             detect_toml_adapter
+          when :yaml, :json
+            detect_yeptris_kv_adapter(format)
           else
             metadata.dig(format, :default)
           end
         end
 
+        # Native key-value engine preference: yeptris (libyeptris C11)
+        # when its gem is in the bundle, else the format's standard
+        # adapter. Opt-in by bundle contents — nothing is required of
+        # consumers that do not add yeptris.
+        def detect_yeptris_kv_adapter(format)
+          return metadata.dig(format, :default) if Lutaml::Model.opal?
+
+          Utils.safe_load("yeptris", :Yeptris) ? :yeptris : metadata.dig(format, :default)
+        end
+
         # Detect available XML adapter.
         #
         # Delegates to moxml which is the authority on XML adapter
@@ -380,17 +392,22 @@ module Lutaml
 
         # Detect available TOML adapter.
         #
-        # @return [Symbol, nil] :tomlib, :toml_rb, or nil
+        # @return [Symbol, nil] :teptris, :tomlib, :toml_rb, or nil
         def detect_toml_adapter
           return nil if Lutaml::Model.opal?
 
-          if RuntimeCompatibility.windows?
-            return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
+          # teptris 0.2.12+ parses ~3x and dumps ~8x faster than
+          # tomlib and ships prebuilts for every platform (mingw-ucrt
+          # restored in 0.2.4+) — native TOML on Windows retires the
+          # tomlib segfault workaround (previously pure-Ruby toml-rb
+          # only).
+          return :teptris if Utils.safe_load("teptris", :Teptris)
 
-            return nil
+          if !RuntimeCompatibility.windows? &&
+              Utils.safe_load("tomlib", :Tomlib)
+            return :tomlib
           end
 
-          return :tomlib if Utils.safe_load("tomlib", :Tomlib)
           return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
 
           nil

data/lib/lutaml/model/attribute.rb

@@ -31,6 +31,29 @@ module Lutaml
         union_member_types
       ].freeze
 
+      # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
+      # Isolated cache holder: enclosing-class freezes (some suites freeze
+      # Lutaml::Model::Attribute) would freeze a constant Hash with it.
+      TypeProbeCache = ::Class.new do
+        class << self
+          def cache
+            @cache ||= {}
+          end
+        end
+      end
+
+      class << self
+        # 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
+            type.method(:from_xml).owner != base ||
+              type.method(:from_json).owner != base
+          end
+        end
+      end
+
       MODEL_STRINGS = [
         Lutaml::Model::Type::String,
         "String",
@@ -252,7 +275,9 @@ module Lutaml
       end
 
       def union?
-        unresolved_type == Lutaml::Model::Type::Union
+        return @union unless @union.nil?
+
+        @union = unresolved_type == Lutaml::Model::Type::Union
       end
 
       def union_member_types
@@ -687,11 +712,11 @@ instance_object = nil)
 
         # Fast path for Type::Value subclasses (String, Integer, Boolean, etc.)
         # These are never Serializable, so skip expensive can_serialize? and needs_conversion? checks
-        # Skip if type has custom from_xml/from_json methods (defined on the class itself, not inherited)
-        if resolved_type.is_a?(Class) && resolved_type < Lutaml::Model::Type::Value
-          has_custom_from_xml = resolved_type.method(:from_xml).owner != Lutaml::Model::Type::Value
-          has_custom_from_json = resolved_type.method(:from_json).owner != Lutaml::Model::Type::Value
-          return resolved_type.cast(value) unless has_custom_from_xml || has_custom_from_json
+        # Skip if type has custom from_xml/from_json methods (defined on the class itself, not inherited).
+        # The probe allocated two Method objects per cast call; the answer is
+        # static per type class, so it is resolved once.
+        if resolved_type.is_a?(Class) && resolved_type < Lutaml::Model::Type::Value && !self.class.custom_from_probe?(resolved_type)
+          return resolved_type.cast(value)
         end
 
         klass = resolve_polymorphic_class(resolved_type, value, options)

data/lib/lutaml/model/configuration.rb

@@ -15,10 +15,15 @@ module Lutaml
     #
     class Configuration
       attr_reader :default_register
+      # Experimental: whole-document native materialization for plan-
+      # compilable XML models (Leptris::XML::Descriptor walk). Opt-in
+      # while the full semantics audit completes.
+      attr_accessor :xml_plan_fast_path
 
       def initialize
         @default_register = :default
         @configured = false
+        @xml_plan_fast_path = false
       end
 
       def configure

data/lib/lutaml/model/error/unknown_adapter_type_error.rb

@@ -3,10 +3,10 @@ module Lutaml
     class UnknownAdapterTypeError < Error
       # Available adapters by format
       AVAILABLE_ADAPTERS = {
-        xml: %w[nokogiri ox oga rexml],
-        json: %w[standard multi_json oj],
-        yaml: %w[standard],
-        toml: %w[tomlib toml_rb],
+        xml: %w[nokogiri ox oga rexml leptris],
+        json: %w[standard multi_json oj yeptris],
+        yaml: %w[standard yeptris],
+        toml: %w[teptris tomlib toml_rb],
         hash: %w[standard],
         jsonl: %w[standard],
         yamls: %w[standard],

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -45,6 +45,11 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The deserialized model instance
         def from(format, data, options = {})
+          if format == :xml && Lutaml::Model::Config.instance.xml_plan_fast_path
+            fast = xml_plan_fast_path(data, options)
+            return fast if fast
+          end
+
           Instrumentation.instrument(:from, model: name, format: format) do
             adapter = resolve_adapter(format, options.delete(:adapter))
 
@@ -76,6 +81,36 @@ module Lutaml
           # No-op by default; XML overrides via prepend
         end
 
+        # Whole-document native materialization (Phase 5): compile the
+        # mapping into a Leptris descriptor plan and hydrate from one
+        # plan walk. Only when the resolved XML adapter is leptris-
+        # backed, the model fully compiles, and no path-affecting
+        # options are present; anything else falls back to the
+        # interpretive pipeline.
+        def xml_plan_fast_path(data, options)
+          return nil unless defined?(::Leptris::XML::Descriptor)
+          return nil if options.key?(:adapter) || options.key?(:only) ||
+            options.key?(:except) || options.key?(:mappings) ||
+            options.key?(:register)
+
+          adapter_name = Lutaml::Model::Config.adapter_for(:xml)
+          adapter_name = adapter_name&.name
+          return nil unless adapter_name.to_s.end_with?("LeptrisAdapter")
+
+          register = Lutaml::Model::Config.default_register
+          plan = Lutaml::Xml::PlanCompiler.compile(self, register)
+          return nil unless plan
+
+          root = ::Leptris::XML.parse(data.to_s).root
+          return nil if root.nil?
+          return nil unless root.name == plan[:tree][:name]
+
+          Lutaml::Xml::PlanHydrator.call(self, plan,
+                                         plan[:descriptor].walk(root))
+        rescue ::Leptris::XML::ParseError => e
+          raise Lutaml::Model::InvalidFormatError.new(:xml, e.message)
+        end
+
         # Get list of error types that can be raised during format parsing.
         # Core errors are always included; format-specific errors come from
         # FormatRegistry registrations.
@@ -119,6 +154,8 @@ module Lutaml
           toml_errors = Array(toml_errors)
           tomllib_err = compatibility.safe_constantize("Tomlib::ParseError")
           toml_errors << tomllib_err if tomllib_err
+          teptris_err = compatibility.safe_constantize("Teptris::ParseError")
+          toml_errors << teptris_err if teptris_err
 
           @format_error_types_base + toml_errors
         end

data/lib/lutaml/model/toml.rb

@@ -7,6 +7,7 @@ module Lutaml
     module Toml
       Lutaml::Model::RuntimeCompatibility.define_native_aliases(
         self,
+        TeptrisAdapter: "::Lutaml::Toml::Adapter::TeptrisAdapter",
         TomlibAdapter: "::Lutaml::Toml::Adapter::TomlibAdapter",
         TomlRbAdapter: "::Lutaml::Toml::Adapter::TomlRbAdapter",
       )
@@ -18,15 +19,18 @@ module Lutaml
       def self.detect_toml_adapter
         return nil if Lutaml::Model.opal?
 
-        # Skip tomlib on Windows entirely due to segfault issues
-        if Lutaml::Model::RuntimeCompatibility.windows?
-          return :toml_rb if Lutaml::Model::Utils.safe_load("toml-rb", :TomlRb)
+        # teptris 0.2.12+ parses ~3x and dumps ~8x faster than tomlib
+        # and ships prebuilts for every platform (mingw-ucrt restored
+        # in 0.2.4+) — native TOML on Windows retires the tomlib
+        # segfault workaround (previously pure-Ruby toml-rb only).
+        return :teptris if Lutaml::Model::Utils.safe_load("teptris", :Teptris)
 
-          return nil
+        # tomlib segfaults on Windows when parsing invalid TOML
+        if !Lutaml::Model::RuntimeCompatibility.windows? &&
+            Lutaml::Model::Utils.safe_load("tomlib", :Tomlib)
+          return :tomlib
         end
 
-        # On non-Windows, prefer tomlib
-        return :tomlib if Lutaml::Model::Utils.safe_load("tomlib", :Tomlib)
         return :toml_rb if Lutaml::Model::Utils.safe_load("toml-rb", :TomlRb)
 
         nil

data/lib/lutaml/model/type/date_time.rb

@@ -1,7 +1,7 @@
-require "date"
-
 # frozen_string_literal: true
 
+require "date"
+
 module Lutaml
   module Model
     module Type

data/lib/lutaml/model/type/value.rb

@@ -2,6 +2,16 @@
 
 module Lutaml
   module Model
+    # Isolated holder for format_type_serializer_for's memo: Type::Value
+    # can be frozen by suites, which would freeze an ivar Hash with it.
+    SERIALIZER_LOOKUP_CACHE = ::Class.new do
+      class << self
+        def cache
+          @cache ||= {}
+        end
+      end
+    end.cache
+
     module Type
       # Base class for all value types
       class Value
@@ -35,14 +45,26 @@ from: nil)
           # @param type_class [Class] the type class to look up
           # @return [Hash, nil] { to: Proc, from: Proc } or nil
           def format_type_serializer_for(format, type_class)
+            # Hot path: memoize per [format, resolved class] — the hierarchy
+            # walk below only runs on a miss. Format serializers register at
+            # load time, so a hit is stable.
+            cache = SERIALIZER_LOOKUP_CACHE
+            key = [format, type_class]
+            return cache[key] if cache.key?(key)
+
             klass = type_class
+            found = nil
             while klass && klass <= Value
               s = @format_type_serializers[[format, klass]]
-              return s if s
+              if s
+                found = s
+                break
+              end
 
               klass = klass.superclass
             end
-            nil
+            cache[key] = found
+            found
           end
         end
 

data/lib/lutaml/model/utils.rb

@@ -121,11 +121,12 @@ module Lutaml
         end
 
         def blank?(value)
-          case value
-          when ::String, ::Array, ::Hash then value.empty?
-          when ::NilClass then true
-          else false
-          end
+          # Hot path: the nil test is a pointer compare, and nil dominates
+          # in optional-field-heavy documents.
+          return true if value.nil?
+          return false unless value.is_a?(::String) || value.is_a?(::Array) || value.is_a?(::Hash)
+
+          value.empty?
         end
 
         def empty_collection?(collection)

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.23"
+    VERSION = "0.8.24"
   end
 end

data/lib/lutaml/toml/adapter/teptris_adapter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../../key_value/adapter/toml/teptris_adapter"
+
+module Lutaml
+  module Toml
+    module Adapter
+      # The implementation lives in the KeyValue namespace (the live
+      # surface for adapter resolution); this alias keeps the legacy
+      # Lutaml::Toml::Adapter surface complete.
+      TeptrisAdapter = Lutaml::KeyValue::Adapter::Toml::TeptrisAdapter
+    end
+  end
+end

data/lib/lutaml/toml/adapter.rb

@@ -11,6 +11,7 @@ module Lutaml
       autoload :Transform, "#{__dir__}/adapter/transform"
       Lutaml::Model::RuntimeCompatibility.autoload_native(
         self,
+        TeptrisAdapter: "#{__dir__}/adapter/teptris_adapter",
         TomlRbAdapter: "#{__dir__}/adapter/toml_rb_adapter",
         TomlibAdapter: "#{__dir__}/adapter/tomlib_adapter",
       )

data/lib/lutaml/toml/format.rb

@@ -35,7 +35,7 @@ Lutaml::Model::FormatRegistry.register(
                      nil
                    else
                      {
-                       available: %i[tomlib toml_rb],
+                       available: %i[teptris tomlib toml_rb],
                        default: Lutaml::Model::RuntimeCompatibility.windows? ? :toml_rb : :tomlib,
                      }
                    end,

data/lib/lutaml/xml/adapter/leptris_adapter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "moxml/adapter/leptris"
+
+module Lutaml
+  module Xml
+    module Adapter
+      class LeptrisAdapter < BaseAdapter
+        MOXML_ADAPTER = Moxml::Adapter::Leptris
+        BUILDER_CLASS = Builder::Leptris
+        PARSED_ELEMENT_CLASS = Lutaml::Xml::LeptrisElement
+      end
+    end
+  end
+end

data/lib/lutaml/xml/adapter_element.rb

@@ -22,7 +22,11 @@ module Lutaml
         text = case node
                when Moxml::Element
                  namespace_name = node.namespace&.prefix
-                 ns_defs = node.namespaces
+                 # moxml >= 0.5.33 contract: #namespaces is the full
+                 # in-scope map (parity with Nokogiri, #198/#201); the
+                 # own-declarations shape this parse path needs is
+                 # #namespace_definitions.
+                 ns_defs = node.namespace_definitions
 
                  has_empty_xmlns = ns_defs.any? do |ns|
                    ns.prefix.nil? && ns.uri == ""
@@ -172,14 +176,118 @@ module Lutaml
       def parse_children(node, default_namespace: nil)
         return [] 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
+        # the element (inner_text) and never touches their wrappers, so
+        # wrapping every text node eagerly paid half the parse tree for
+        # nothing. #children wraps them on first access; document order
+        # is preserved because they sit at their original positions.
         node.children.filter_map do |child|
           next if (child.is_a?(Moxml::Text) || child.is_a?(Moxml::Cdata)) && child.content.empty?
 
-          self.class.new(child, parent: self,
-                                default_namespace: default_namespace)
+          if child.is_a?(Moxml::Element)
+            self.class.new(child, parent: self,
+                                  default_namespace: default_namespace)
+          else
+            child
+          end
         end
       end
 
+      public
+
+      def children
+        unless @non_element_children_wrapped
+          @children.map! do |child|
+            if child.is_a?(Moxml::Node) && !child.is_a?(Moxml::Element)
+              self.class.new(child, parent: self)
+            else
+              child
+            end
+          end
+          @non_element_children_wrapped = true
+        end
+        @children
+      end
+
+      def children=(new_children)
+        @non_element_children_wrapped = true
+        super
+      end
+
+      def element_children
+        return @element_children if defined?(@element_children)
+
+        @element_children = @children.reject do |child|
+          raw_non_element_child?(child) ||
+            (child.is_a?(XmlElement) &&
+              (child.text? || child.processing_instruction?))
+        end
+      end
+
+      def raw_non_element_child?(child)
+        child.is_a?(Moxml::Node) && !child.is_a?(Moxml::Element)
+      end
+
+      # Order consumes raw non-element children inline: wrapping them
+      # just to read .text/.content would materialize the whole lazy
+      # layer on every parse.
+      def order
+        return @order_cache if @order_cache
+
+        @order_cache = @children.filter_map do |child|
+          case child
+          when Moxml::Cdata
+            Lutaml::Xml::Element.new("Text", "#cdata-section",
+                                     text_content: child.content,
+                                     node_type: :cdata)
+          when Moxml::Text
+            next if child.content.nil?
+
+            Lutaml::Xml::Element.new("Text", "text",
+                                     text_content: child.content,
+                                     node_type: :text)
+          when Moxml::Comment
+            Lutaml::Xml::Element.new("Comment", "comment",
+                                     text_content: child.content,
+                                     node_type: :comment)
+          when Moxml::ProcessingInstruction
+            Lutaml::Xml::Element.new("ProcessingInstruction",
+                                     child.target,
+                                     text_content: child.content.to_s.sub(/\A\s+/, ""),
+                                     node_type: :processing_instruction)
+          else
+            next if child.is_a?(Moxml::Node)
+
+            if child.cdata?
+              Lutaml::Xml::Element.new("Text", "#cdata-section",
+                                       text_content: child.text,
+                                       node_type: :cdata)
+            elsif child.text?
+              next if child.text.nil?
+
+              Lutaml::Xml::Element.new("Text", "text",
+                                       text_content: child.text,
+                                       node_type: :text)
+            elsif child.comment?
+              Lutaml::Xml::Element.new("Comment", "comment",
+                                       text_content: child.text,
+                                       node_type: :comment)
+            elsif child.processing_instruction?
+              Lutaml::Xml::Element.new("ProcessingInstruction",
+                                       child.unprefixed_name,
+                                       text_content: child.text,
+                                       node_type: :processing_instruction)
+            else
+              Lutaml::Xml::Element.new("Element", child.unprefixed_name,
+                                       node_type: :element,
+                                       namespace_uri: child.namespace_uri,
+                                       namespace_prefix: child.namespace_prefix)
+            end
+          end
+        end.each(&:freeze).freeze
+      end
+
       def add_namespaces_from_defs(ns_defs, is_root: false)
         has_default_xmlns = is_root || ns_defs.any? { |ns| ns.prefix.nil? }
 

data/lib/lutaml/xml/builder/base.rb

@@ -223,7 +223,9 @@ module Lutaml
             ns = new_el.in_scope_namespaces.find { |n| n.prefix == prefix }
             new_el.namespace = ns if ns
           elsif !prefix_unset && prefix.nil?
-            new_el.namespace = nil
+            # Skip the no-op clear: namespace-less elements pay the
+            # undeclare path on some engines (leptris) for nothing.
+            new_el.namespace = nil unless new_el.namespace.nil?
           end
         end
 

data/lib/lutaml/xml/builder/leptris.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Builder
+      class Leptris < Base
+        def self.moxml_backend
+          :leptris
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/builder/nokogiri.rb

@@ -4,6 +4,9 @@ module Lutaml
   module Xml
     module Builder
       class Nokogiri < Base
+        def self.moxml_backend
+          :nokogiri
+        end
       end
     end
   end

data/lib/lutaml/xml/builder.rb

@@ -11,6 +11,7 @@ module Lutaml
         self,
         Nokogiri: "#{__dir__}/builder/nokogiri",
         Ox: "#{__dir__}/builder/ox",
+        Leptris: "#{__dir__}/builder/leptris",
       )
     end
   end

data/lib/lutaml/xml/format.rb

@@ -21,6 +21,8 @@ end
 
 module Lutaml
   module Xml
+    autoload :PlanCompiler, "#{__dir__}/plan_compiler"
+    autoload :PlanHydrator, "#{__dir__}/plan_hydrator"
     # Error module for XML-specific errors
     module Error
       autoload :XmlError, "#{__dir__}/error/xml_error"
@@ -161,6 +163,7 @@ module Lutaml
       NokogiriElement: "#{__dir__}/nokogiri/element",
       Nokogiri: "#{__dir__}/nokogiri",
       Ox: "#{__dir__}/ox",
+      LeptrisElement: "#{__dir__}/leptris/element",
     )
   end
 end
@@ -192,7 +195,7 @@ Lutaml::Model::FormatRegistry.register(
                      }
                    else
                      {
-                       available: %i[nokogiri ox oga rexml],
+                       available: %i[nokogiri ox oga rexml leptris],
                        default: :nokogiri,
                      }
                    end,

data/lib/lutaml/xml/leptris/element.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    class LeptrisElement < AdapterElement
+      def initialize(node, parent: nil, default_namespace: nil)
+        @raw_text = node.raw_content if node.is_a?(Moxml::Text)
+        super
+      end
+
+      private
+
+      def adapter_class
+        Lutaml::Xml::Adapter::LeptrisAdapter
+      end
+
+      def build_text_for_xml
+        @raw_text || @text
+      end
+
+      def build_element_xml(builder)
+        builder.create_and_add_element(name,
+                                       prefix: namespace_prefix,
+                                       attributes: build_attributes(self)) do |xml|
+          children.each { |child| child.build_xml(xml) }
+        end
+      end
+
+      def attribute_value_for_build(attr)
+        attr.raw_value
+      end
+    end
+  end
+end