lutaml-model 0.8.157 → 0.8.159

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/opal.yml +5 -0
  3. data/docs/_guides/opal.adoc +11 -0
  4. data/docs/_pages/serialization_adapters.adoc +18 -2
  5. data/lib/lutaml/key_value/transformation/value_serializer.rb +21 -0
  6. data/lib/lutaml/key_value/transformation.rb +57 -6
  7. data/lib/lutaml/model/adapter_resolver.rb +29 -0
  8. data/lib/lutaml/model/cached_type_resolver/concurrent_map_cache.rb +3 -1
  9. data/lib/lutaml/model/cached_type_resolver/mutex_hash_cache.rb +3 -1
  10. data/lib/lutaml/model/cached_type_resolver.rb +13 -22
  11. data/lib/lutaml/model/collection.rb +63 -6
  12. data/lib/lutaml/model/collection_handler.rb +9 -13
  13. data/lib/lutaml/model/mapping/mapping_rule.rb +28 -4
  14. data/lib/lutaml/model/serialize/builder.rb +1 -1
  15. data/lib/lutaml/model/serialize/enum_handling.rb +7 -3
  16. data/lib/lutaml/model/serialize/format_conversion.rb +26 -1
  17. data/lib/lutaml/model/serialize/value_mapping.rb +6 -0
  18. data/lib/lutaml/model/serialize.rb +6 -1
  19. data/lib/lutaml/model/services/rule_value_extractor.rb +39 -35
  20. data/lib/lutaml/model/utils.rb +16 -4
  21. data/lib/lutaml/model/version.rb +1 -1
  22. data/lib/lutaml/xml/adapter/oga_adapter.rb +4 -0
  23. data/lib/lutaml/xml/adapter/rexml_adapter.rb +4 -0
  24. data/lib/lutaml/xml/adapter_element.rb +16 -21
  25. data/lib/lutaml/xml/declaration_planner.rb +63 -3
  26. data/lib/lutaml/xml/schema/xsd/schema_path.rb +8 -3
  27. data/spec/lutaml/model/collection_scalar_maps_spec.rb +58 -0
  28. data/spec/lutaml/model/key_value_accepted_values_spec.rb +99 -0
  29. data/spec/lutaml/xml/schema/xsd/glob_spec.rb +14 -18
  30. data/spec/lutaml/xml/schema/xsd/unresolvable_schema_location_spec.rb +58 -0
  31. metadata +5 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 5a7a7b4352ec266e959f6a4304acafba60a4433953c36fdd3c4cfc2d7bafeccf
4
- data.tar.gz: 827c5280c74a9d9c6a517adc00779444ba0c305fbecab9ab8ccc491a2f09ddc0
3
+ metadata.gz: b57a42ee46afb01c4b14ed7b3a9f7563d8f7a88ff567ca912cd31304865f3b53
4
+ data.tar.gz: 5d2e30a7d52e49f45bec3b8cdd302c181ab9c284e8046bed5b32a00f3bc4098c
5
5
  SHA512:
6
- metadata.gz: bc20f062d7a51cd5c9bcaf5e7df729ba80551e161a146611773d5e8697650fa9dad7f83424c93ef95e0b75fe4db118b844ef2661891b6499c896c226f29c3d0e
7
- data.tar.gz: 1874b8520c7cca77ffaac37e985f69d80fcb242d8c66b53e10c94cf4f8c12eee9930650e6f36cb03b93ce3f5e3c15115136deebb0865c438f79884bc24f881c8
6
+ metadata.gz: 3a6d56103c63a1bf5552f25a7766e3b791ce14b3e83cf755c4e2f346bd70c84cf163d396a198423b4957594684fc0de2112a8b9c603d409dd77ca643fee18560
7
+ data.tar.gz: 6da4328f548094e614753bd012e75261b770929aa7115ad4bf307ec5170f9de03ef6b943806882a53d4801cfc33b8e3bd046779d0a6e2a07cc719f1728a97615
@@ -1,3 +1,8 @@
1
+ # DEPRECATED: the Opal lane is on the deprecation path (the moxml-ts
2
+ # wasm binding is the JavaScript endgame). The lane stays green — the
3
+ # boot repair chain lives in lib/compat/opal — but it is
4
+ # maintenance-only and non-gating; removal is planned for a future
5
+ # release.
1
6
  name: opal
2
7
 
3
8
  on:
@@ -11,6 +11,17 @@ nav_order: 99
11
11
 
12
12
  == Overview
13
13
 
14
+ [IMPORTANT]
15
+ ====
16
+ Opal support in lutaml-model is **deprecated**. The Opal boot lane, its
17
+ compat shims, and the vendored Opal forks remain functional in the 0.8
18
+ line but receive maintenance-only attention, and removal is planned for
19
+ a future release. New JavaScript-targeted work is directed at the
20
+ moxml-ts wasm binding instead.
21
+ ====
22
+
23
+
24
+
14
25
  https://opalrb.com[Opal] is a Ruby-to-JavaScript compiler that allows Ruby code to run in the browser. Lutaml::Model supports running under Opal, enabling XML/JSON/YAML serialization in client-side applications.
15
26
 
16
27
  The XML parsing layer is provided by the https://github.com/lutaml/moxml[moxml] gem (v0.2+), which detects the Opal runtime and uses the REXML adapter automatically.
@@ -190,11 +190,19 @@ Requires native extensions (i.e. compiled C code).
190
190
  Requires the `nokogiri` gem.
191
191
 
192
192
  Oga::
193
- (optional)
193
+ (optional, *deprecated*)
194
194
  Pure Ruby XML parser.
195
195
  Does not require native extensions.
196
196
  Requires the `oga` gem.
197
197
 
198
+ [NOTE]
199
+ ====
200
+ The Oga engine is deprecated: moxml's default engine (Nokogiri, or the
201
+ leptris native engine when present) is the supported XML lane.
202
+ Selecting Oga emits a deprecation warning; removal is planned for a
203
+ future release.
204
+ ====
205
+
198
206
  Ox::
199
207
  (optional)
200
208
  Fast XML parser and object serializer for Ruby, implemented partially in C.
@@ -202,13 +210,21 @@ Requires native extensions (i.e. compiled C code).
202
210
  Requires the `ox` gem.
203
211
 
204
212
  REXML::
205
- (optional)
213
+ (optional, *deprecated*)
206
214
  Pure Ruby XML parser, bundled as a default gem with Ruby.
207
215
  Moved from standard library to a default gem in Ruby 3.0.
208
216
  Opal-compatible: Opal reimplements `strscan` and `stringio` in its stdlib,
209
217
  enabling REXML to compile cleanly to JavaScript.
210
218
  Requires the `rexml` gem (bundled with Ruby by default).
211
219
 
220
+ [NOTE]
221
+ ====
222
+ The REXML engine is deprecated: moxml's default engine (Nokogiri, or
223
+ the leptris native engine when present) is the supported XML lane.
224
+ Selecting REXML emits a deprecation warning; removal is planned for a
225
+ future release.
226
+ ====
227
+
212
228
 
213
229
  .Using an XML adapter
214
230
  [source,ruby]
@@ -114,6 +114,7 @@ model_class: nil)
114
114
  # @param options [Hash] Serialization options
115
115
  # @return [Hash, nil] The serialized hash or nil if empty
116
116
  def serialize_nested_model(value, rule, options = {})
117
+ value = coerce_nested_for_rule(value, rule)
117
118
  validate_nested_model_type!(value, rule)
118
119
 
119
120
  # Determine the actual type for polymorphism support
@@ -152,6 +153,7 @@ model_class: nil)
152
153
  # For Serializable types, use to_#{format} method
153
154
  if rule.attribute_type.is_a?(Class) &&
154
155
  rule.attribute_type < Lutaml::Model::Serialize
156
+ value = coerce_nested_for_rule(value, rule)
155
157
  validate_serializable_type!(value, rule)
156
158
  return value.public_send(:"to_#{format}")
157
159
  end
@@ -245,6 +247,25 @@ model_class: nil)
245
247
 
246
248
  private
247
249
 
250
+ # Coerce a value the model accepted into the rule's declared
251
+ # nested class (#1089) before the validators run. Registered
252
+ # type substitutions pass through untouched — the validators
253
+ # accept them as-is.
254
+ #
255
+ # @param value [Object] The stored attribute value
256
+ # @param rule [CompiledRule] The compiled rule
257
+ # @return [Object] The coerced value, or the value unchanged
258
+ def coerce_nested_for_rule(value, rule)
259
+ expected = rule.attribute_type.model || rule.attribute_type
260
+ return value if value.is_a?(expected)
261
+
262
+ context = Lutaml::Model::GlobalContext.context(register_id)
263
+ return value if context.substitution_for(rule.attribute_type)
264
+ .any? { |s| s.to_type == value.class }
265
+
266
+ NestedValueCoercion.coerce(value, expected)
267
+ end
268
+
248
269
  # Validate that a nested model value matches the expected type.
249
270
  #
250
271
  # @param value [Object] The value to validate
@@ -15,6 +15,44 @@ module Lutaml
15
15
  #
16
16
  # This is a critical step toward symmetric OOP architecture
17
17
  # across all serialization formats.
18
+ # Coerces values the model layer accepted into a rule's declared
19
+ # nested type (lutaml-model#1089): constructors and writers accept
20
+ # raw hashes, sibling Serializable instances, and content scalars,
21
+ # but the KeyValue serializer demanded exact declared-class
22
+ # instances — accept-then-explode mid-render. Hashes construct
23
+ # directly; Serializable siblings round-trip through the framework
24
+ # hash; scalars wrap onto the declared type's content attribute
25
+ # when its XML mapping declares one (`map_content to: :x` — the
26
+ # same semantics the XML lane applies to text). Genuinely
27
+ # un-coercible values pass through unchanged so the caller's
28
+ # validation raises with its own message.
29
+ module NestedValueCoercion
30
+ @content_attributes = {}.compare_by_identity
31
+
32
+ # The attribute a declared type's XML mapping designates as its
33
+ # textual content. Class-level memo: the answer is a static
34
+ # per-type mapping fact. Keyed by type only; register-specific
35
+ # content mappings are not a supported combination.
36
+ def self.content_attribute_for(type)
37
+ @content_attributes[type] ||= begin
38
+ mapping = type.mappings_for(:xml)
39
+ mapping&.content_mapping&.to
40
+ end
41
+ end
42
+
43
+ def self.coerce(value, declared_class)
44
+ if value.is_a?(::Hash)
45
+ declared_class.new(value)
46
+ elsif value.is_a?(Lutaml::Model::Serialize)
47
+ declared_class.new(value.to_hash)
48
+ elsif (content_key = content_attribute_for(declared_class))
49
+ declared_class.new(content_key => value)
50
+ else
51
+ value
52
+ end
53
+ end
54
+ end
55
+
18
56
  class Transformation < Lutaml::Model::Transformation
19
57
  # Builtin Value types whose cast of an already-native value is the
20
58
  # identity — used by the serialize_value fast path.
@@ -1037,6 +1075,10 @@ child_mappings, options)
1037
1075
  # @param value [Object] The value
1038
1076
  # @param options [Hash] Options
1039
1077
  # @return [Object] The value (could be Hash, primitive, or KeyValueElement)
1078
+ def coerce_accepted_nested_value(value, declared_class)
1079
+ NestedValueCoercion.coerce(value, declared_class)
1080
+ end
1081
+
1040
1082
  # Child transformations memoized on this transformation instance:
1041
1083
  # the factory binds this instance's mapping/format/register, so
1042
1084
  # the memo is register-safe, and building one per serialized node
@@ -1083,15 +1125,21 @@ child_mappings, options)
1083
1125
  # Mapper class: value should be an instance of the mapped model
1084
1126
  # or a valid substituted type
1085
1127
  unless value.is_a?(rule.attribute_type.model) || uses_type_substitution
1086
- msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a '#{rule.attribute_type.model}'"
1087
- raise Lutaml::Model::IncorrectModelError, msg
1128
+ value = coerce_accepted_nested_value(value, rule.attribute_type.model)
1129
+ unless value.is_a?(rule.attribute_type.model)
1130
+ msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a '#{rule.attribute_type.model}'"
1131
+ raise Lutaml::Model::IncorrectModelError, msg
1132
+ end
1088
1133
  end
1089
1134
  else
1090
1135
  # Regular Serializable class: value should be a Serialize instance
1091
1136
  # or a valid substituted type
1092
1137
  unless value.is_a?(Lutaml::Model::Serialize) || uses_type_substitution
1093
- msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a kind of 'Lutaml::Model::Serialize'"
1094
- raise Lutaml::Model::IncorrectModelError, msg
1138
+ value = coerce_accepted_nested_value(value, rule.attribute_type)
1139
+ unless value.is_a?(Lutaml::Model::Serialize)
1140
+ msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a kind of 'Lutaml::Model::Serialize'"
1141
+ raise Lutaml::Model::IncorrectModelError, msg
1142
+ end
1095
1143
  end
1096
1144
  end
1097
1145
 
@@ -1191,8 +1239,11 @@ child_mappings, options)
1191
1239
  # When attribute_type is a Serializable class, value must be an instance of that class
1192
1240
  if plan[:nested]
1193
1241
  unless value.is_a?(rule.attribute_type)
1194
- msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a '#{rule.attribute_type}'"
1195
- raise Lutaml::Model::IncorrectModelError, msg
1242
+ value = coerce_accepted_nested_value(value, rule.attribute_type)
1243
+ unless value.is_a?(rule.attribute_type)
1244
+ msg = "attribute '#{rule.attribute_name}' value is a '#{value.class}' but should be a '#{rule.attribute_type}'"
1245
+ raise Lutaml::Model::IncorrectModelError, msg
1246
+ end
1196
1247
  end
1197
1248
 
1198
1249
  # Value is a valid Serialize instance - serialize it using its own to_#{format} method
@@ -29,6 +29,21 @@ module Lutaml
29
29
  #
30
30
  class AdapterResolver
31
31
  class << self
32
+ # Adapters on the deprecation path. moxml is the only supported
33
+ # XML facade going forward, and its default engine (Nokogiri,
34
+ # with the leptris native engine preferred when present) is the
35
+ # supported lane; the pure-Ruby REXML and Oga engines remain
36
+ # loadable but select for the last time in the 0.8 line.
37
+ DEPRECATED_ADAPTERS = {
38
+ %i[xml rexml] => "the REXML engine is deprecated; moxml's " \
39
+ "default engine (Nokogiri, or the leptris " \
40
+ "native engine when present) is the supported " \
41
+ "XML lane",
42
+ %i[xml oga] => "the Oga engine is deprecated; moxml's default " \
43
+ "engine (Nokogiri, or the leptris native engine " \
44
+ "when present) is the supported XML lane",
45
+ }.freeze
46
+
32
47
  # --- Resolution ---
33
48
 
34
49
  # Resolve the adapter class for a format using the full resolution chain.
@@ -215,12 +230,26 @@ module Lutaml
215
230
  adapter = format.to_s
216
231
  type = normalize_type_name(type_name, format)
217
232
 
233
+ warn_deprecated_adapter(format, type_name)
218
234
  load_adapter_file(adapter, type)
219
235
  load_moxml_adapter(type_name, format)
220
236
 
221
237
  class_for(adapter, type)
222
238
  end
223
239
 
240
+ # One deprecation warning per (format, adapter) per process.
241
+ def warn_deprecated_adapter(format, type_name)
242
+ message = DEPRECATED_ADAPTERS[[format, type_name.to_sym]]
243
+ return if message.nil? || warned_deprecated.key?([format, type_name])
244
+
245
+ warned_deprecated[[format, type_name]] = true
246
+ warn "[Lutaml::Model] DEPRECATED: #{message}."
247
+ end
248
+
249
+ def warned_deprecated
250
+ @warned_deprecated ||= {}
251
+ end
252
+
224
253
  # Normalize type name to file/class name pattern.
225
254
  #
226
255
  # @param type_name [Symbol] raw type name
@@ -29,7 +29,9 @@ module Lutaml
29
29
 
30
30
  def clear_context(context_id)
31
31
  @store.each_key do |key|
32
- @store.delete(key) if key[0] == context_id
32
+ # Non-Array keys are the bare, nil-context form (see
33
+ # CachedTypeResolver#type_cache_key).
34
+ @store.delete(key) if (key.is_a?(Array) ? key[0] : nil) == context_id
33
35
  end
34
36
  end
35
37
 
@@ -34,7 +34,9 @@ module Lutaml
34
34
 
35
35
  def clear_context(context_id)
36
36
  @mutex.synchronize do
37
- @store.delete_if { |key, _| key[0] == context_id }
37
+ # Non-Array keys are the bare, nil-context form (see
38
+ # CachedTypeResolver#type_cache_key).
39
+ @store.delete_if { |key, _| (key.is_a?(Array) ? key[0] : nil) == context_id }
38
40
  end
39
41
  end
40
42
 
@@ -65,13 +65,7 @@ module Lutaml
65
65
  def resolve(name, context, materialize: true)
66
66
  return @delegate.resolve(name, context, materialize: false) unless materialize
67
67
 
68
- cache_key = if name.is_a?(Class)
69
- [context_id_for(context), name]
70
- else
71
- build_cache_key(name, context)
72
- end
73
-
74
- @cache_backend.fetch_or_store(cache_key) do
68
+ @cache_backend.fetch_or_store(type_cache_key(name, context)) do
75
69
  @delegate.resolve(name, context)
76
70
  end
77
71
  end
@@ -82,13 +76,7 @@ module Lutaml
82
76
  # @param context [TypeContext, nil] The resolution context
83
77
  # @return [Boolean] true if type can be resolved
84
78
  def resolvable?(name, context)
85
- cache_key = if name.is_a?(Class)
86
- [context_id_for(context), name]
87
- else
88
- build_cache_key(name, context)
89
- end
90
-
91
- return true if @cache_backend.key?(cache_key)
79
+ return true if @cache_backend.key?(type_cache_key(name, context))
92
80
 
93
81
  @delegate.resolvable?(name, context)
94
82
  end
@@ -133,14 +121,17 @@ module Lutaml
133
121
 
134
122
  private
135
123
 
136
- # Build a cache key from name and context.
137
- # Uses array for faster comparison than string concatenation.
138
- #
139
- # @param name [Symbol, String] The type name
140
- # @param context [TypeContext, nil] The resolution context
141
- # @return [Array] The cache key (faster than string)
142
- def build_cache_key(name, context)
143
- [context_id_for(context), name.to_sym]
124
+ # Composite cache key: `[context_id, name]` when a context is present,
125
+ # otherwise the bare name (Symbol or Class). The bare form avoids one
126
+ # Array allocation per resolution in the common single-register run;
127
+ # it cannot collide with composite keys since Arrays and
128
+ # Symbols/Classes never match as Hash keys. Keys belonging to the nil
129
+ # context are therefore the non-Array ones (see the backends'
130
+ # #clear_context).
131
+ def type_cache_key(name, context)
132
+ bare = name.is_a?(Class) ? name : name.to_sym
133
+ cid = context_id_for(context)
134
+ cid ? [cid, bare] : bare
144
135
  end
145
136
 
146
137
  # A nil context (e.g. a register ID that has no registered type
@@ -75,6 +75,12 @@ module Lutaml
75
75
  end
76
76
  end
77
77
 
78
+ # Frozen per-subclass ivar name for the `collection` accessors —
79
+ # see the instance-method memo below.
80
+ def collection_ivar_name
81
+ @collection_ivar_name ||= :"@#{instance_name}"
82
+ end
83
+
78
84
  attr_reader :instance_type,
79
85
  :instance_name,
80
86
  :sort_by_field,
@@ -325,7 +331,11 @@ module Lutaml
325
331
  mappings = mappings_for(format)
326
332
  data = super
327
333
 
328
- if !collection_structured_format?(format) && mappings.no_root? && !mappings.root_mapping
334
+ # Scalar mappings make the document hash-shaped (#1086): the
335
+ # unwrap below would strip it back to a bare items array and
336
+ # drop the scalar keys.
337
+ if !collection_structured_format?(format) && mappings.no_root? &&
338
+ !mappings.root_mapping && !collection_has_scalar_mappings?(format)
329
339
  unwrap_unwrapped_data(data)
330
340
  else
331
341
  data
@@ -339,19 +349,50 @@ module Lutaml
339
349
  data = wrap_unwrapped_input(format, mappings, data)
340
350
  end
341
351
 
352
+ # Hash-shaped documents (scalar mappings declared, #1086) walk
353
+ # the rules like any model: the collection flag would treat the
354
+ # document as the bare items array and lose the scalar keys.
355
+ if !collection_structured_format?(format) &&
356
+ collection_has_scalar_mappings?(format) && data.is_a?(::Hash)
357
+ return super(format, data, options.merge(from_collection: true))
358
+ end
359
+
342
360
  super(format, data, options.merge(from_collection: true))
343
361
  end
344
362
 
345
363
  def of(format, data, options = {})
346
364
  mappings = mappings_for(format)
347
365
 
348
- if !collection_structured_format?(format) && mappings.no_root? && !mappings.root_mapping
366
+ # Hash-shaped documents carrying a declared scalar key (#1086)
367
+ # are already keyed; the no-root wrap would double-nest them.
368
+ # Bare arrays (the legacy items document), keyed-element
369
+ # documents (child_mappings walks the hash keys), and scalar-less
370
+ # collections all keep the historical wrap.
371
+ if !collection_structured_format?(format) && mappings.no_root? &&
372
+ !mappings.root_mapping && data.is_a?(::Array)
373
+ data = { mappings.find_by_to!(instance_name).name => data }
374
+ elsif !collection_structured_format?(format) && data.is_a?(::Hash) &&
375
+ collection_has_scalar_mappings?(format) &&
376
+ !(data.keys & collection_scalar_mapping_names(format)).empty?
377
+ # keep the keyed document as-is
378
+ elsif !collection_structured_format?(format) && mappings.no_root? &&
379
+ !mappings.root_mapping
349
380
  data = { mappings.find_by_to!(instance_name).name => data }
350
381
  end
351
382
 
352
383
  super(format, data, options.merge(from_collection: true))
353
384
  end
354
385
 
386
+ # Names of the collection's scalar (non-instance) key-value
387
+ # mappings (#1086).
388
+ def collection_scalar_mapping_names(format)
389
+ instance = instance_name
390
+ mappings_for(format).mappings
391
+ .reject { |rule| rule.to == instance }
392
+ .flat_map { |rule| Array(rule.name) }
393
+ .compact
394
+ end
395
+
355
396
  # Hook: returns true for formats that use structured (tree-based) serialization
356
397
  # like XML. Key-value formats (JSON, YAML, TOML) return false (default).
357
398
  # XML overrides to return true.
@@ -431,11 +472,23 @@ module Lutaml
431
472
 
432
473
  attr_reader :lutaml_register
433
474
 
434
- def initialize(items = [],
475
+ # Shared frozen empty array for the constructor's default argument;
476
+ # `items` is only read in initialize, never mutated.
477
+ EMPTY_ITEMS = [].freeze
478
+
479
+ def initialize(items = EMPTY_ITEMS,
435
480
  lutaml_register: Lutaml::Model::Config.default_register)
481
+ # Seed constructor-equivalent state in one compiled pass
482
+ # (#1059's walk-seed) and stand the generic walk down via the
483
+ # seed flag: 92% of a materialization corpus's constructor
484
+ # invocations are Collection wrappers whose generic super()
485
+ # walk only materialized defaults that the items mapping below
486
+ # overwrites again.
487
+ self.lutaml_constructor_seeded = true
488
+ init_walk_state(lutaml_register)
436
489
  super()
490
+ self.lutaml_constructor_seeded = nil
437
491
 
438
- @lutaml_register = lutaml_register
439
492
  items = [items].compact unless items.is_a?(Array)
440
493
 
441
494
  type = Lutaml::Model::GlobalContext.resolve_type(
@@ -460,12 +513,16 @@ lutaml_register: Lutaml::Model::Config.default_register)
460
513
  super(format, options.merge(collection: true))
461
514
  end
462
515
 
516
+ # The ivar name is static per subclass (set by `instances`); the
517
+ # dynamic :"@#{...}" symbol minted per access was 11% of a
518
+ # YAML-materialization profile's allocations (56k per 60 docs on
519
+ # the glossarist corpus). The name is memoized on the class.
463
520
  def collection
464
- instance_variable_get(:"@#{self.class.instance_name}")
521
+ instance_variable_get(self.class.collection_ivar_name)
465
522
  end
466
523
 
467
524
  def collection=(collection)
468
- instance_variable_set(:"@#{self.class.instance_name}", collection)
525
+ instance_variable_set(self.class.collection_ivar_name, collection)
469
526
  sort_items!
470
527
  build_index_caches!
471
528
  end
@@ -57,21 +57,17 @@ module Lutaml
57
57
  # so thread it through when one is supplied. Plain Array collections and
58
58
  # register-less callers keep the prior construction path untouched.
59
59
  #
60
- # @param args [Array] Values to include in the collection
60
+ # The former *args splat + flatten ceremony allocated a splat Array
61
+ # plus a keyword-options hash per call (15k+ per corpus parse);
62
+ # every call site passes at most one already-flat Array, and
63
+ # Attribute#assert_flat_collection_items! guards nesting loudly.
64
+ #
65
+ # @param items [Array, nil] Values to include in the collection
61
66
  # @param register [Symbol, nil] Register for custom-collection type resolution
62
67
  # @return [Object] A new collection instance
63
- def build_collection(*args, register: nil)
64
- # args.flatten allocated a fresh Array even for the dominant
65
- # calls: no args, or one already-flat Array from cast_items
66
- # (71,949 flatten allocations per ISO-13849 parse).
67
- items = if args.empty?
68
- []
69
- elsif args.length == 1 && (first = args[0]).is_a?(::Array) &&
70
- first.none?(::Array)
71
- first
72
- else
73
- args.flatten
74
- end
68
+ def build_collection(items = nil, register: nil)
69
+ items = [] if items.nil?
70
+ items = [items] unless items.is_a?(::Array)
75
71
  unless register && initialize_accepts_register?
76
72
  return collection_class.new(items)
77
73
  end
@@ -566,18 +566,42 @@ context = nil, pre_cast: false)
566
566
  end
567
567
  end
568
568
 
569
+ # Pooled invokers for symbol/string custom methods, keyed by
570
+ # [mapper class, method]. The receiver is stateless in the #550
571
+ # contract — it receives the model and value as arguments — but a
572
+ # fresh mapper_class.new per rule application ran the full
573
+ # Serializable constructor chain on every call (33% of a YAML
574
+ # materialization profile on the glossarist corpus). One receiver
575
+ # per (class, method) is pooled, with the arity probe resolved
576
+ # once alongside it. A custom method that stashes instance state
577
+ # on the receiver would observe cross-call persistence — today's
578
+ # fresh receiver discarded that state between calls, so such
579
+ # methods were already broken call-over-call.
580
+ def custom_method_invokers
581
+ @custom_method_invokers ||= {}
582
+ end
583
+
584
+ def custom_method_invoker(mapper_class, custom)
585
+ custom_method_invokers[[mapper_class, custom]] ||= begin
586
+ receiver = mapper_class.new
587
+ { receiver: receiver,
588
+ context_arity:
589
+ self.class.custom_method_arity(receiver.class, custom).to_i >= 3 }
590
+ end
591
+ end
592
+
569
593
  def handle_custom_method(model, value, mapper_class, context = nil)
570
594
  custom = custom_methods[:from]
571
595
  return if !custom || value.nil?
572
596
 
573
597
  if custom.is_a?(String) || custom.is_a?(Symbol)
574
- target = mapper_class.new
598
+ invoker = custom_method_invoker(mapper_class, custom)
575
599
  # lutaml-model#550: custom methods may declare a third context
576
600
  # parameter to receive the options passed to `from_*`.
577
- if self.class.custom_method_arity(target.class, custom).to_i >= 3
578
- target.public_send(custom, model, value, context)
601
+ if invoker[:context_arity]
602
+ invoker[:receiver].public_send(custom, model, value, context)
579
603
  else
580
- target.public_send(custom, model, value)
604
+ invoker[:receiver].public_send(custom, model, value)
581
605
  end
582
606
  else
583
607
  # Callable (proc/lambda): transforms the value and the rule
@@ -33,7 +33,7 @@ module Lutaml
33
33
  # @param attrs [Hash] Attribute values (ignored when block given)
34
34
  # @param options [Hash] Options (ignored when block given)
35
35
  # @param block [Proc, nil] Optional builder block
36
- def initialize(attrs = {}, options = {}, &block)
36
+ def initialize(attrs = EMPTY_HASH, options = EMPTY_HASH, &block)
37
37
  # Call parent initialize
38
38
  super(attrs, options)
39
39
 
@@ -134,6 +134,10 @@ module Lutaml
134
134
  # @param collection [Boolean] Whether the enum is a collection
135
135
  def add_enum_setter_if_not_defined(klass, enum_name, _values,
136
136
  collection)
137
+ # Static per-definition symbols close over instead of being
138
+ # minted per setter call (11k+ per corpus parse).
139
+ ivar = :"@#{enum_name}"
140
+ reader = enum_name.to_sym
137
141
  Utils.add_method_if_not_defined(klass, "#{enum_name}=") do |value|
138
142
  value = [] if value.nil?
139
143
  value = [value] if !value.is_a?(Array)
@@ -141,16 +145,16 @@ module Lutaml
141
145
  value_set_for(enum_name)
142
146
 
143
147
  if collection
144
- curr_value = public_send(:"#{enum_name}")
148
+ curr_value = public_send(reader)
145
149
 
146
150
  # Build a new Array rather than appending into the stored one.
147
151
  # The reader hands back the real Array now, so `curr_value` may
148
152
  # be this model's own collection — or, when the model defines
149
153
  # its own reader, something shared between instances or not an
150
154
  # Array at all. Duplicates are the reader's job either way.
151
- instance_variable_set(:"@#{enum_name}", curr_value + value)
155
+ instance_variable_set(ivar, curr_value + value)
152
156
  else
153
- instance_variable_set(:"@#{enum_name}", value)
157
+ instance_variable_set(ivar, value)
154
158
  end
155
159
  end
156
160
  end
@@ -433,7 +433,18 @@ module Lutaml
433
433
  resolve_serialization_mapping_option(format, options)
434
434
 
435
435
  if instance.is_a?(Array)
436
- return instance.map { |item| public_send(:"as_#{format}", item) }
436
+ # Collection subclasses that declare scalar key-value mappings
437
+ # serialize hash-shaped (#1086): their rules include
438
+ # non-instance keys, so the per-item map would silently drop
439
+ # them. Plain Arrays and legacy collections (instances-only
440
+ # mappings) keep the per-item map.
441
+ if instance.is_a?(Lutaml::Model::Collection) &&
442
+ !collection_structured_format?(format) &&
443
+ collection_has_scalar_mappings?(format)
444
+ # fall through to the rule walk below
445
+ else
446
+ return instance.map { |item| public_send(:"as_#{format}", item) }
447
+ end
437
448
  end
438
449
 
439
450
  unless instance.is_a?(model)
@@ -454,6 +465,20 @@ module Lutaml
454
465
  transformer.model_to_data(self, instance, format, options)
455
466
  end
456
467
 
468
+ # Whether the bound Collection class declares key-value mappings
469
+ # beyond its instance collection rule (#1086). Such mappings make
470
+ # the document hash-shaped (instance key plus scalar keys) instead
471
+ # of the legacy bare items array.
472
+ def collection_has_scalar_mappings?(format)
473
+ return false unless model < Lutaml::Model::Collection
474
+
475
+ mappings = model.mappings_for(format)
476
+ instance_name = model.instance_name
477
+ mappings.mappings.any? { |rule| rule.to != instance_name }
478
+ rescue StandardError
479
+ false
480
+ end
481
+
457
482
  # Hook for format-specific pre-serialization logic.
458
483
  # XML overrides to resolve XML mapping imports.
459
484
  #
@@ -111,6 +111,12 @@ module Lutaml
111
111
  # Opal strings are JS strings with no per-string encoding;
112
112
  # String#encode there doesn't accept MRI's keyword options.
113
113
  return value if Lutaml::Model.opal?
114
+ # The encode-with-options forces a fresh copy per value even
115
+ # when the string is already valid UTF-8 — the overwhelming
116
+ # case on parsed documents. Scan instead: no allocation on
117
+ # the happy path; encode still runs for genuinely invalid
118
+ # input.
119
+ return value if value.encoding == Encoding::UTF_8 && value.valid_encoding?
114
120
 
115
121
  value.encode("UTF-8", invalid: :replace, undef: :replace,
116
122
  replace: "")