lutaml-model 0.8.17 → 0.8.18

data/lib/compat/opal/moxml_boot.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Opal-only boot for moxml — mirrors moxml's shipped
+# `lib/compat/opal/moxml_boot.rb` so both Oga and REXML adapters are
+# eager-loaded (Opal ignores autoload; without this, nested Moxml
+# constants NameError at runtime).
+#
+# Requires the REXML gem's lib dir to be on Opal's load path so
+# `require "rexml/formatters/pretty"` (pulled in by moxml's
+# customized_rexml/formatter) resolves. The Rakefile sets that up.
+#
+# moxml's own boot loads the same list. We maintain our own copy so we
+# can reorder or gate entries if a future moxml release introduces an
+# Opal-incompatible file before its shipped boot catches up.
+
+if RUBY_ENGINE == "opal"
+  require "moxml/version"
+  require "moxml/error"
+  require "moxml/native_attachment"
+  require "moxml/native_attachment/opal"
+  require "moxml/xml_utils"
+  require "moxml/xml_utils/encoder"
+  require "moxml/node"
+  require "moxml/node_set"
+  require "moxml/document"
+  require "moxml/element"
+  require "moxml/attribute"
+  require "moxml/text"
+  require "moxml/cdata"
+  require "moxml/comment"
+  require "moxml/processing_instruction"
+  require "moxml/declaration"
+  require "moxml/namespace"
+  require "moxml/doctype"
+  require "moxml/entity_reference"
+  require "moxml/entity_registry"
+  require "moxml/adapter"
+  require "moxml/adapter/base"
+  require "moxml/adapter/customized_rexml"
+  require "moxml/adapter/customized_rexml/entity_reference"
+  require "moxml/adapter/customized_rexml/formatter"
+  require "moxml/sax"
+  require "moxml/sax/handler"
+  require "moxml/sax/element_handler"
+  require "moxml/sax/block_handler"
+  require "moxml/sax/namespace_splitter"
+  require "moxml/adapter/rexml"
+  require "moxml/adapter/customized_oga"
+  require "moxml/adapter/customized_oga/xml_declaration"
+  require "moxml/adapter/customized_oga/xml_generator"
+  require "moxml/adapter/oga"
+  require "moxml/document_builder"
+  require "moxml/builder"
+  require "moxml/context"
+  require "moxml/config"
+  require "moxml/xpath"
+  require "moxml/xpath/engine"
+  require "moxml/xpath/context"
+  require "moxml/xpath/conversion"
+  require "moxml/xpath/cache"
+  require "moxml/xpath/lexer"
+  require "moxml/xpath/parser"
+  require "moxml/xpath/compiler"
+  require "moxml/xpath/errors"
+  require "moxml/xpath/ast/node"
+  require "moxml/xpath/ruby/node"
+  require "moxml/xpath/ruby/generator"
+end

data/lib/compat/opal/yaml_compat.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Opal runtime YAML compat.
+#
+# Opal's `nodejs/yaml` ships `YAML.load` only. lutaml-model's YAML adapter
+# uses `YAML.safe_load(src, permitted_classes: [...])` and `YAML.dump(obj)`.
+# Provide both as thin wrappers — nodejs/yaml is already backed by
+# jsyaml.safeLoad, so `load` semantics are equivalent to MRI's safe_load
+# with the default permitted classes (the perm_classes argument is
+# accepted but ignored, matching Opal's stronger-by-default posture).
+
+if RUBY_ENGINE == "opal"
+  require "nodejs/yaml"
+
+  module ::YAML
+    class << self
+      # Accept MRI's full safe_load kwargs for API parity; nodejs/yaml's
+      # safeLoad is already safe-by-default so the kwargs are unused.
+      def safe_load(yaml, **_kwargs)
+        load(yaml)
+      end
+
+      def dump(obj, io = nil)
+        dumped = `#{@__yaml__}.safeDump(#{obj})`
+        return dumped unless io
+
+        io.write(dumped)
+        io
+      end
+    end
+  end
+end

data/lib/lutaml/json.rb

@@ -34,7 +34,7 @@ module Lutaml
 
     # Detect available JSON adapters
     def self.detect_adapter
-      return :standard if defined?(::JSON) && Lutaml::Model::RuntimeCompatibility.opal?
+      return :standard if defined?(::JSON) && Lutaml::Model.opal?
       return :oj if defined?(::Oj)
       return :multi_json if defined?(::MultiJson)
       return :standard if defined?(::JSON)

data/lib/lutaml/key_value/transform.rb

@@ -249,8 +249,9 @@ format)
         value = apply_value_map(value, rule.value_map(:from, options), attr)
 
         if rule.has_custom_method_for_deserialization?
-          return process_custom_method(rule, instance,
-                                       value)
+          return unless Lutaml::Model::Utils.present?(value)
+
+          return rule.deserialize(instance, value, attributes, model_class)
         end
 
         value = rule.transform_value(attr, value, :from, format)
@@ -265,12 +266,6 @@ format)
         rule.deserialize(instance, value, attributes, self)
       end
 
-      def process_custom_method(rule, instance, value)
-        return unless Lutaml::Model::Utils.present?(value)
-
-        model_class.new.public_send(rule.custom_methods[:from], instance, value)
-      end
-
       def cast_value(value, attr, format, rule, instance)
         cast_options = rule.polymorphic ? { polymorphic: rule.polymorphic } : {}
         cast_options[:lutaml_parent] = instance if instance

data/lib/lutaml/key_value/transformation/value_serializer.rb

@@ -63,13 +63,26 @@ model_class: nil)
             return serialize_reference(value, rule)
           end
 
-          if nested_model?(rule)
+          if Lutaml::Model::Type::Union.rule?(rule)
+            serialize_union(value, options)
+          elsif nested_model?(rule)
             serialize_nested_model(value, rule, options)
           else
             serialize_primitive(value, rule)
           end
         end
 
+        # Union: dispatch on the value's own class (stateless). A model member
+        # serializes via its class transformation; a scalar emits as-is.
+        def serialize_union(value, options)
+          unless value.is_a?(Lutaml::Model::Serialize)
+            return Lutaml::Model::Type::Union.serialize_scalar(value, format)
+          end
+
+          transform_nested_model(value, create_transformation(value.class),
+                                 options)
+        end
+
         # Check if a value is a nested model based on the rule.
         #
         # @param rule [CompiledRule] The compiled rule

data/lib/lutaml/key_value/transformation.rb

@@ -936,9 +936,15 @@ child_mappings, options)
       def create_value_for_item(rule, value, options)
         return nil if value.nil?
 
-        # Check if this is a nested model
-        is_nested_model = rule.attribute_type.is_a?(Class) &&
-          rule.attribute_type < Lutaml::Model::Serialize
+        # Union: dispatch on the value's own class (stateless, like polymorphism).
+        # A model member serializes via its class; a scalar member emits as-is.
+        union = Lutaml::Model::Type::Union.rule?(rule)
+        is_nested_model = if union
+                            value.is_a?(Lutaml::Model::Serialize)
+                          else
+                            rule.attribute_type.is_a?(Class) &&
+                              rule.attribute_type < Lutaml::Model::Serialize
+                          end
 
         if is_nested_model
           # Validate that value matches the expected type
@@ -970,8 +976,9 @@ child_mappings, options)
           # If value is a subclass of the declared type, use its mappings instead
           # Also handle type substitution the same way
           actual_type = value.class
-          uses_polymorphism = (actual_type != rule.attribute_type &&
-            actual_type < rule.attribute_type) || uses_type_substitution
+          uses_polymorphism = union ||
+            (actual_type != rule.attribute_type &&
+              actual_type < rule.attribute_type) || uses_type_substitution
 
           # Get child transformation - may be cached or need to create
           child_transformation = rule.child_transformation
@@ -998,6 +1005,11 @@ child_mappings, options)
             # Fallback: serialize as primitive
             serialize_value(value, rule)
           end
+        elsif union
+          # Union scalar: serialize through the value type matching the value's
+          # own class so output is canonical (e.g. BigDecimal -> "1.5"), not a
+          # raw Ruby object.
+          Lutaml::Model::Type::Union.serialize_scalar(value, format)
         else
           # Serialize primitive value
           serialize_value(value, rule)

data/lib/lutaml/model/adapter_resolver.rb

@@ -231,7 +231,7 @@ module Lutaml
           end
 
           # Default key-value adapter loading
-          adapter_path = if RuntimeCompatibility.opal?
+          adapter_path = if Lutaml::Model.opal?
                            "lutaml/key_value/adapter/#{adapter}/#{type}"
                          else
                            File.join(File.dirname(__FILE__), "../key_value/adapter",
@@ -382,7 +382,7 @@ module Lutaml
         #
         # @return [Symbol, nil] :tomlib, :toml_rb, or nil
         def detect_toml_adapter
-          return nil if RuntimeCompatibility.opal?
+          return nil if Lutaml::Model.opal?
 
           if RuntimeCompatibility.windows?
             return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)

data/lib/lutaml/model/attribute.rb

@@ -28,6 +28,7 @@ module Lutaml
         ref_model_class
         ref_key_attribute
         xsd_type
+        union_member_types
       ].freeze
 
       MODEL_STRINGS = [
@@ -239,6 +240,15 @@ module Lutaml
         @options[:polymorphic_class]
       end
 
+      def union?
+        unresolved_type == Lutaml::Model::Type::Union
+      end
+
+      def union_member_types
+        @union_member_types ||=
+          @options[:union_member_types].map { |member| cast_type!(member) }
+      end
+
       def derived?
         !method_name.nil?
       end
@@ -276,6 +286,43 @@ module Lutaml
         build_collection(value.map { |v| cast_element(v, register) })
       end
 
+      # Apply a value map to transform a value.
+      #
+      # value_map keys (:nil, :empty, :omitted) each map either to a symbolic
+      # option (:nil, :empty, :omitted) or, for Boolean attributes, directly
+      # to true/false. The nested form value_map[:from][key] = true/false is
+      # accepted unconditionally; the bare form value_map[key] = true/false
+      # is gated on the attribute being a Boolean type.
+      def apply_value_map(value, value_map)
+        key = if value.nil? then :nil
+              elsif Utils.empty?(value) then :empty
+              elsif Utils.uninitialized?(value) then :omitted
+              end
+        return value unless key
+
+        nested = value_map.dig(:from, key)
+        return nested if nested.is_a?(TrueClass) || nested.is_a?(FalseClass)
+
+        option = value_map[key]
+        if (option.is_a?(TrueClass) || option.is_a?(FalseClass)) &&
+            (type == Lutaml::Model::Type::Boolean ||
+             unresolved_type == Lutaml::Model::Type::Boolean)
+          return option
+        end
+
+        case option
+        when :nil
+          nil
+        when :empty
+          if key == :empty then value
+          elsif collection? then build_collection
+          else ""
+          end
+        else
+          Lutaml::Model::UninitializedClass.instance
+        end
+      end
+
       def required_value_set?(value)
         return true unless options[:required]
         return false if value.nil?
@@ -286,6 +333,7 @@ module Lutaml
 
       def cast_element(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?
 
         # Special handling for Reference types - pass the metadata
@@ -398,12 +446,19 @@ instance_object = nil)
         options[:values].include?(value)
       end
 
+      # Pattern binds string values only. For a plain :string attribute that is
+      # the resolved type; for a union, the pattern applies to a value that took
+      # the :string branch (a non-string member is exempt). Collections check
+      # each element, so a mix of members validates only its string entries.
       def valid_pattern!(value, resolved_type)
-        return true unless resolved_type == Lutaml::Model::Type::String
         return true unless pattern
 
-        unless pattern.match?(value)
-          raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, value)
+        Array(value).each do |item|
+          next unless resolved_type == Lutaml::Model::Type::String ||
+            item.is_a?(::String)
+          next if pattern.match?(item)
+
+          raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, item)
         end
 
         true
@@ -419,11 +474,11 @@ instance_object = nil)
       #   2. Value count should be between the collection range if defined
       #      e.g if collection: 0..5 is set then the value greater then 5
       #          will raise `Lutaml::Model::CollectionCountOutOfRangeError`
-      def validate_value!(value, register, resolver = nil)
+      def validate_value!(value, register, instance_object: nil)
         # Use the default value if the value is nil
         validate_required!(value)
 
-        value = resolver&.default if value.nil?
+        value = cast_value(default_value(register, instance_object), register) if value.nil?
         resolved_type = type(register)
 
         valid_value!(value) &&
@@ -587,6 +642,8 @@ instance_object = nil)
 
         return value if already_serialized?(resolved_type, value)
 
+        return cast_union(value, format, register) if union?
+
         # Special handling for Reference types - pass the metadata
         # Check @options[:ref_model_class] which is set when type is { ref: [...] }
         if @options[:ref_model_class] && resolved_type == Lutaml::Model::Type::Reference
@@ -664,6 +721,11 @@ instance_object = nil)
 
       def process_options!
         validate_options!(@options)
+        if union?
+          @options[:union_member_types] =
+            Lutaml::Model::Type::Union.validate_members!(@options[:union_member_types])
+          Lutaml::Model::Type::Union.validate_combo!(@options)
+        end
         @raw = !!@options[:raw]
         if @raw
           warn "[DEPRECATED] attribute :#{name}, :string, raw: true is deprecated. " \
@@ -776,6 +838,13 @@ instance_object = nil)
 
       attr_writer :raw, :validations
 
+      def cast_union(value, format, register)
+        match = Lutaml::Model::Type::Union.conforming_member(
+          value, union_member_types, format: format, register: register
+        )
+        match&.last
+      end
+
       def validate_attr_type!(resolved_type)
         return true if resolved_type <= Serializable || resolved_type <= Type::Value
         return true if resolved_type.include?(Serialize)
@@ -931,12 +1000,20 @@ instance_object = nil)
                "Called from #{caller(1..1).first}"
         end
 
-        # No need to change user register#get_class, only checks if type is LutaML-Model string.
-        # Using MODEL_STRINGS since pattern is only supported for String type.
-        if options.key?(:pattern) && !MODEL_STRINGS.include?(type)
-          raise StandardError,
-                "Invalid option `pattern` given for `#{name}`, " \
-                "`pattern` is only allowed for :string type"
+        # pattern applies to string values: a plain :string attribute, or a
+        # union that includes a :string member (the pattern binds that branch).
+        # Guarded by the pattern key so non-pattern attributes never resolve
+        # their type here (custom types may be absent from the default register).
+        if options.key?(:pattern)
+          union_with_string =
+            type == Lutaml::Model::Type::Union &&
+            Array(options[:union_member_types]).intersect?(MODEL_STRINGS)
+          unless MODEL_STRINGS.include?(type) || union_with_string
+            raise StandardError,
+                  "Invalid option `pattern` given for `#{name}`, " \
+                  "`pattern` is only allowed for :string type or a union " \
+                  "including a :string member"
+          end
         end
 
         if initialize_empty? && !collection?

data/lib/lutaml/model/cached_type_resolver.rb

@@ -36,7 +36,7 @@ module Lutaml
       attr_reader :delegate, :cache_backend
 
       def self.default_cache_backend
-        if RuntimeCompatibility.opal?
+        if Lutaml::Model.opal?
           MutexHashCache.new
         else
           ConcurrentMapCache.new

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

@@ -0,0 +1,11 @@
+module Lutaml
+  module Model
+    class UnionSchemaUnsupportedError < Error
+      def initialize(attribute, format)
+        super("Union-typed attribute `#{attribute}` cannot be exported to " \
+              "#{format}; union types are only representable in JSON Schema " \
+              "(anyOf).")
+      end
+    end
+  end
+end

data/lib/lutaml/model/global_context.rb

@@ -324,10 +324,13 @@ context_id = nil)
       end
 
       class << self
-        # Performance: Define delegation methods without closures
-        # Using class_eval with string avoids closure allocation per call
+        # Block form: avoids Opal's runtime string parsing requirement
+        # (MRI's class_eval(string) needs `require 'opal-parser'` at
+        # runtime under Opal, which isn't bundled). Closures are
+        # allocated once at file load, not per call, so the perf cost
+        # over the previous string form is negligible.
 
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        class_eval do
           def registry
             instance.registry
           end
@@ -356,8 +359,8 @@ context_id = nil)
             instance.default_context
           end
 
-          def context(*args, **kwargs, &block)
-            instance.context(*args, **kwargs, &block)
+          def context(id = nil)
+            instance.context(id)
           end
 
           def clear_xml_namespace_registry!
@@ -404,8 +407,8 @@ context_id = nil)
             instance.resolvable?(name, ctx)
           end
 
-          def with_context(ctx_id)
-            instance.with_context(ctx_id) { yield }
+          def with_context(ctx_id, &block)
+            instance.with_context(ctx_id, &block)
           end
 
           def register_format_registry(format, registry)
@@ -440,7 +443,7 @@ context_id = nil)
           def namespace_register_map
             instance.namespace_register_map
           end
-        RUBY
+        end
       end
     end
   end

data/lib/lutaml/model/instrumentation.rb

@@ -155,7 +155,7 @@ module Lutaml
         #
         # @return [Float] the current monotonic time in seconds
         def monotonic_time
-          return Time.now.to_f if Lutaml::Model::RuntimeCompatibility.opal?
+          return Time.now.to_f if Lutaml::Model.opal?
 
           Process.clock_gettime(Process::CLOCK_MONOTONIC)
         end
@@ -164,7 +164,7 @@ module Lutaml
         #
         # @return [Integer, nil] memory in bytes, or nil if not available
         def memory_usage
-          return nil if Lutaml::Model::RuntimeCompatibility.opal?
+          return nil if Lutaml::Model.opal?
           return nil unless defined?(GC)
 
           GC.start if RUBY_VERSION >= "2.7"

data/lib/lutaml/model/mapping/mapping_rule.rb

@@ -248,12 +248,6 @@ module Lutaml
         polymorphic_map && !polymorphic_map.empty?
       end
 
-      def serialize_attribute(model, element, doc)
-        if custom_methods[:to]
-          model.public_send(custom_methods[:to], model, element, doc)
-        end
-      end
-
       def to_value_for(model)
         if delegate
           model.public_send(delegate).public_send(to)

data/lib/lutaml/model/register.rb

@@ -48,7 +48,7 @@ module Lutaml
       # Cache for resolve_for_child results.
       # Key: [child_class.object_id, parent_register] → Value: resolved register Symbol or nil.
       # Classes are singletons so object_id is stable for the process lifetime.
-      RESOLVE_CACHE = if RuntimeCompatibility.opal?
+      RESOLVE_CACHE = if Lutaml::Model.opal?
                         {}
                       else
                         Concurrent::Map.new
@@ -82,7 +82,7 @@ module Lutaml
       def self.resolve_for_child(child_class, parent_register)
         cache_key = [child_class.object_id, parent_register]
 
-        if RuntimeCompatibility.opal?
+        if Lutaml::Model.opal?
           return RESOLVE_CACHE[cache_key] if RESOLVE_CACHE.key?(cache_key)
 
           RESOLVE_CACHE[cache_key] =

data/lib/lutaml/model/runtime_compatibility.rb

@@ -91,4 +91,54 @@ if Lutaml::Model::RuntimeCompatibility.opal?
       end
     end
   end
+
+  # Opal has no `weakref` stdlib. Store uses WeakRef to let go of
+  # registered instances automatically once they go out of scope.
+  # Under Opal (browser JS GC) we substitute a strong reference —
+  # correct behavior, weaker memory profile, no API surface change.
+  unless defined?(WeakRef)
+    class ::WeakRef
+      class RefError < ::StandardError; end
+
+      def initialize(obj)
+        @__target__ = obj
+      end
+
+      def __getobj__
+        @__target__
+      end
+
+      def weakref_alive?
+        true
+      end
+
+      # Minimal method_missing so the WeakRef quacks like its target
+      # for the Store's index lookups.
+      def method_missing(name, *, &)
+        @__target__.public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @__target__.respond_to?(name, include_private)
+      end
+    end
+  end
+
+  # Opal's Module#prepend raises "Prepending a module multiple times
+  # is not supported" when a module is already in the target's ancestor
+  # chain. MRI's prepend is idempotent in that case (no-op, no error).
+  #
+  # Our top-level lib files (lib/lutaml/model.rb, lib/lutaml/xml.rb)
+  # can be re-evaluated under Opal's eager loader, which would trigger
+  # the raise on the second pass. Align Opal with MRI by making prepend
+  # a no-op when the module is already present.
+  class ::Module
+    unless method_defined?(:__lm_original_prepend__)
+      alias_method :__lm_original_prepend__, :prepend
+
+      def prepend(mod)
+        __lm_original_prepend__(mod) unless self <= mod
+      end
+    end
+  end
 end

data/lib/lutaml/model/schema/class_loader.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+unless RUBY_ENGINE == "opal"
+  require "fileutils"
+  require "tmpdir"
+end
+
+module Lutaml
+  module Model
+    module Schema
+      # Writes a CompiledOutput to a temporary directory, requires the
+      # registry, and runs `register_all` so the generated classes are
+      # loaded into a real module the caller can use immediately. Shared
+      # between XSD and RNG compilers.
+      class ClassLoader
+        DEFAULT_NAMESPACE = "GeneratedModels"
+
+        def self.load(output, registry_generator: RegistryGenerator)
+          new(output, registry_generator).load
+        end
+
+        def initialize(output, registry_generator)
+          # ClassLoader needs a module to host the registry constant
+          # (so `register_all` has a home). If the caller wanted
+          # unwrapped class files, we still force a registry module —
+          # but we pin `source_module_namespace` to what they asked for,
+          # so per-class files keep their original wrapping.
+          @output = CompiledOutput.new(
+            entries: output.entries,
+            module_namespace: output.module_namespace || DEFAULT_NAMESPACE,
+            register_id: output.register_id,
+            source_module_namespace: output.module_namespace,
+          )
+          @registry_generator = registry_generator
+        end
+
+        def load
+          Dir.mktmpdir do |dir|
+            FileWriter.write(@output, dir, registry_generator: @registry_generator)
+            require File.join(dir, "#{registry_basename}_registry")
+            call_register_all
+          end
+        end
+
+        private
+
+        def registry_basename
+          @output.module_namespace.split("::").last.downcase
+        end
+
+        def call_register_all
+          mod = Object.const_get(@output.module_namespace)
+          mod.register_all if mod.respond_to?(:register_all)
+        end
+      end
+    end
+  end
+end