Skip to content

3.12.0

Choose a tag to compare

@plutext plutext released this 06 Nov 03:58
· 3 commits to master since this release

An unknown element no longer has to fail a whole read. With onUnexpectedElement set, the two cases that used to stop the unmarshal are now reported and skipped, as an unknown element in a class of named properties always was:

var unmarshaller = context.createUnmarshaller({
  onUnexpectedElement: function (name, node, classInfo) { /* record it, or throw to fail the read */ }
});

What it does. Set, each of these calls the callback once and drops the element with all it holds:

  • An element a list or wildcard property can neither type nor hold as DOM (allowDom: false). It used to fail with ... is not known in this context and the property does not allow DOM content.
  • A child of a class with no element or value content. It used to fail with Illegal state: must be END_ELEMENT.

The read then carries on with the next sibling. Text inside a reported element is not reported separately.

What stays. Set or unset:

  • The document root keeps its throw. There is no property to report it against and nothing to read.
  • A child of an element with a value or a simple type keeps its throw (Element text content may not contain START_ELEMENT.).
  • A wildcard that keeps an element keeps it and reports nothing.

Unset, both errors are exactly what they were. onUnexpectedText alone doesn't turn either into a report. The callback's signature and the typings' shapes are unchanged; types/main.d.ts updates its notes.

Why. @docx4j/core-ts reads a part on past an unknown element and reports it (its CR-026). Before this, whether such an element failed the part depended on how its parent class was mapped, not on the element.

Cost. Not measurable. On objects' model, reads are within the run-to-run range of 3.11.0, unset and set.

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

  • @docx4j/generated-objects-ts: typecheck and npm test identical to 3.11.0's on Node 18, 20 and 22, and all 341 marshal hashes match.
  • @docx4j/core-ts: npm test 1,884 of 1,884. Of Word check 76's 98 sources, 2 fail where 68 fail on 3.11.0, and those 2 are core-ts's own. All 15,679 saved parts are unchanged by this release.

What a consumer must do. If you don't set onUnexpectedElement, nothing. If you do, a read that used to fail in these two cases now completes, with the element reported and dropped. Treat a report as content lost, or throw from the callback to keep the failure, which is then located. The runtime's jsonix-factory.js in this release is byte-identical to the bytes objects and core-ts tested (sha256 c8070eaac0248985f8d964ca90baf84095e195d36249cc2c6fffa248f81d34c9, commit 0936c2f).

The reasoning is in docs/change-requests/jsonix-CR-015-report-an-element-a-property-cannot-hold.md.