Skip to content

3.13.0

Latest

Choose a tag to compare

@plutext plutext released this 07 Nov 02:27

A single-valued property given a second element keeps the last, and until now nothing said so. A new per-call option reports it:

var unmarshaller = context.createUnmarshaller({
  onOverwrittenElement: function (node, keptNode, propertyInfo, classInfo, value, keptValue) { /* record it, or throw to fail the read */ }
});

What it does. Set, it is called once for each value overwritten, after both values are complete, so three elements give two calls. node and value are what is lost, and keptNode and keptValue are what the tree holds. It covers a named element, an elements choice, an element reference and a single wildcard. Where a property has a wrapper element, node is the wrapper.

What it doesn't report. A collection, a map, a mixed property, or a second element that gives no value (<n>5</n><n/>, n an Integer), since nothing is overwritten there. Two children in one wrapper still throw Value already set., set or unset.

What stays. The runtime stores the last value, set or unset, and merges nothing. The return value is ignored. keptValue is the object stored, so a caller can join or merge by editing it. To refuse the document, throw: the error is located at the second element, and node gives the first's line. A report is not a validity claim: it says the model holds one, not that the schema allows one.

Why. Word doesn't keep the last. Of two w:body, it shows both, and a keep-the-last read loses the first's words with nothing reported, so @docx4j/core-ts's save gate couldn't refuse that loss. No file in either dependent's corpus has the shape. The rules for reading such a file as Word does belong above the runtime: @docx4j/generated-objects-ts's CR-022 applies them through this callback.

Cost. Unset, none shows: reads on objects' model are within the run-to-run range of 3.12.0. Set, about 3 ms in 115, with the ranges overlapping.

What the dependents checked. Each ran a package built from the implementing commit against 3.12.0:

  • @docx4j/generated-objects-ts: typecheck and npm test pass on Node 18, 20 and 22 unset, and on Node 22 with the callback set on every read. All 341 marshal hashes are unchanged, and set gives 0 reports. The 13 repeated shapes measured in Word report once each.
  • @docx4j/core-ts: its suite gives the same result as 3.12.0 on the same build, on Node 22 and 24. Across 1,045 packages, all results match 3.12.0, the 1,026 saved hash identically, and set gives 0 reports.

What a consumer must do. Nothing, unless you want the report. The runtime's jsonix-factory.js in this release is byte-identical to the bytes objects and core-ts tested (sha256 81003a28fa1bd3b262bcc11c067a98bd74fd008ef55fc630ffe1112e2136fb58, commit 959d98a).

The reasoning is in docs/change-requests/jsonix-CR-016-report-an-overwritten-element.md.