Skip to content

Releases

3.13.0

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.

3.12.0

Choose a tag to compare

@plutext plutext released this 06 Nov 03:58

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.

3.11.0

Choose a tag to compare

@plutext plutext released this 28 Oct 00:30

A caller can now declare the type of an element a wildcard holds, when reading and when saving. It is one per-call option, the same on both factories, and unset by default:

var options = {
  wildcardTypeInfo: function (name, parent, propertyInfo, classInfo, elementOrValue) { /* return a type info, or undefined */ }
};
context.createUnmarshaller(options);
context.createMarshaller(options);

What it does. A wildcard (an anyElement property, such as the content of mc:Choice or mc:Fallback) types each element it holds by the element's declaration: the class's scope first, then the global one. Where an element's type depends on where it appears, the global declaration wins. In WordprocessingML the global w:sdt is block level, so a run-level content control in a paragraph's mc:Choice read as SdtBlock, with everything below it. An SdtRun in the same place was saved with xsi:type. wildcardTypeInfo is asked before that lookup:

  • name is the element's name.
  • parent is the element the wildcard's class is reading or writing: in the source document when reading, and the open element in the output document when saving.
  • propertyInfo is the wildcard property, and classInfo is its class.
  • The last argument is the element itself when reading, and the value when saving.

Because parent means the same on both sides, one function that decides by name and ancestry can go in one options object to both factories.

A returned type info is the element's declared type. When reading, it decides the class and every list below it, and it can type an element the context doesn't declare. When saving, xsi:type is written only where the value's class differs from the answer. Answer with a type info from the context in use, because the comparison is by identity. With supportXsiType off, the value is marshalled by the answer. undefined or null keeps the lookup by name, and anything else throws.

When reading, it is asked at the element's start, before its onElement. It is not asked when supportXsiType is on and the element's xsi:type names a known type, which still comes first, nor for a DOM-only wildcard. A throw is located, for example w:sdt (line 3): .... When saving, it is asked for each typed value before omitElement and before the element is written. It is never asked for mixed text or DOM content. The typings add wildcardTypeInfo? to UnmarshalCallbacks and MarshalCallbacks.

Why. @docx4j/generated-objects-ts types a content control in a kept mc:Choice or mc:Fallback at its host's level: run, row, cell or block (its CR-018), which is what docx4j does. The level is known only from the ancestors, so it has to be decided where the runtime picks the type, before the element is read.

Cost. On 3,000 paragraphs, each with a run-level control in an mc:Choice (6,000 elements in wildcards, objects' 104 modules), reading and saving are within noise of 3.10.0, unset and set. objects checked the candidate:

  • all 341 of its fidelity hashes are identical to 3.10.0's, unset and set;
  • its CR-018 forms read at their host's level, with no xsi:type;
  • their saves are byte-identical to 3.10.0's.

What a consumer must do. Nothing. Unset, nothing is called and nothing changes. The runtime's jsonix-factory.js in this release is byte-identical to the bytes objects tested (sha256 906bc9f2a9b4254c58975a42aac38c6f76b1867db6c926b24ccfdc36ebc7061d, commit ce4db33).

Change request: docs/change-requests/jsonix-CR-014-declare-wildcard-element-types.md

3.10.0

Choose a tag to compare

@plutext plutext released this 27 Oct 20:57

Character data that unmarshalling drops can now be reported. This is a per-call unmarshaller option beside onUnexpectedElement and onUnexpectedAttribute, unset by default:

context.createUnmarshaller({
  onUnexpectedText: function (text, node, classInfo) { /* ... */ }
})

What it does. <w:r>MISPLACED<w:t>x</w:t></w:r> unmarshals as a run holding w:t alone, and until now no callback fired for the lost string. onUnexpectedText is called once for each text or CDATA node that is dropped and that holds a character other than XML whitespace (space, tab, CR, LF):

  • text is the node's text as parsed, untrimmed.
  • node is the text or CDATA node itself. Its parentNode is the containing element, and in Node it carries lineNumber and columnNumber.
  • classInfo is the containing element's class info.

Text is dropped, and now reported, in three places:

  • the element content of a class with no mixed property (a run, a paragraph, the body);
  • any text inside an element whose class has no content (<w:b>x</w:b>);
  • in any class, text the runtime treats as space although XML does not. For example, a lone U+00A0 or U+3000 in a run was dropped as if it were blank.

Whitespace-only text is never reported. Neither is text inside an element that onUnexpectedElement reports. A comment splits a text into two calls.

Calls come in document order with onUnexpectedElement's, before the containing element's onElement. The text stays dropped, and the return value is ignored. A callback that throws stops the unmarshal, located as #text (line N): .... The typings add UnmarshalCallbacks.onUnexpectedText?.

Why. @docx4j/generated-objects-ts reports misplaced children (its CR-017). A string read inside a run was the one misplaced form that vanished with no trace anywhere: Word 365's repair and JAXB drop it too. With this release, objects can report it, and core-ts can warn on load.

Cost. Unset, unmarshalling is within noise of 3.9.0. Set, it is about 2% slower on a pretty-printed document, the whitespace test on each indentation node. Across objects' fidelity corpus (359 checks), the option reported nothing. With it unset, every re-marshalled part was byte-identical to 3.9.0's.

What a consumer must do. Nothing. The runtime's jsonix-factory.js in this release is byte-identical to commit c259464, which objects tested.

Change request: docs/change-requests/jsonix-CR-013-report-dropped-character-data.md

3.9.0

Choose a tag to compare

@plutext plutext released this 25 Oct 22:42

An integer attribute can now be read strictly, so that only an optional sign and digits are accepted. This is a per-call unmarshaller option, off by default:

context.createUnmarshaller({
  strictIntegers: true,
  onInvalidValue: function (text, propertyInfo, classInfo, node, error) { /* ... */ }
})

What it does. The integer parse reads text with Number(). So "", " 240 ", 240., 10206.0, 0x10 and 1e3 all read as integers, and none of them reach 3.7.0's onInvalidValue. With strictIntegers, an attribute of Integer or any of its twelve restrictions (Long, Int, UnsignedLong, ...) accepts only /^[+-]?[0-9]+$/.

  • Every other text is refused. It goes to onInvalidValue exactly as written or, if that is unset, fails with a located error: w:spacing/@w:before (line 3): Argument [ 240 ] must be an integer literal: an optional + or - and the digits 0 to 9, with nothing around them.
  • A text that the lenient parse already refuses (1.5, abc) fails with the same error as before.
  • No whitespace is trimmed. This is deliberately stricter than XSD, which collapses whitespace in xs:integer, because Word 365 refuses a document holding " 240 ".

Reading as before. propertyInfo.typeInfo.parse(text) is still the lenient parse. A callback can call it to keep the runtime's reading for some vocabularies: it returns the value, or throws the error, as without the option. The typings add TypeInfo.parse? for this, and UnmarshallerOptions.strictIntegers?.

Unchanged: element content, simple content, list items, enumerations, Decimal/Double, range checks (there are none, on or off) and marshalling. The Context constructor does not read the option.

Why. docx4j CR-065's shared Word 365 probe found the following:

  • Word refuses the whole document for whitespace around an integer, for hex and for exponents.
  • It reads "" as 0 and a decimal by truncation.

@docx4j/generated-objects-ts reads Word's forms through onInvalidValue (its CR-015). Until now, the forms Number() accepts never reached it.

Cost. Unset, unmarshalling is within noise of 3.8.0. With the option on, the check costs about 40 ns per integer attribute.

What a consumer must do. Nothing.

Change request: docs/change-requests/jsonix-CR-012-strict-integer-attributes.md

3.8.0

Choose a tag to compare

@plutext plutext released this 24 Oct 02:19

The marshaller can now change what it writes without changing the objects in memory. This is the runtime's counterpart of JAXB's XmlAdapter, set per call:

context.createMarshaller({
  onAttributeValue: function (value, text, owner, propertyInfo, classInfo) { /* a string, null, or undefined */ },
  omitElement: function (value, name, typeInfo, propertyInfo, classInfo) { /* true to leave it out */ }
})

onAttributeValue is called for an attribute value that printed. It gets the value, text (what the runtime would write), owner (the typed object being marshalled, so sibling properties can be read), the property info and the class info that declares it.

  • A returned string is written.
  • null omits the attribute.
  • undefined keeps text, so a callback can fall through for the properties it does not handle.

A value that fails to print still goes only to 3.7.0's onUnprintableValue.

omitElement is called before each element written from a property, with its value, name, type (after xsi:type), property info and owning class info. That covers element, elements and element-ref properties, revision lists included, and the typed items of a wildcard. Returning true leaves the element out: no start element, no content, no onElement report. The root passed to marshal* is never offered.

Scope. Both callbacks receive class or type infos carrying module.name, so a policy can be confined to one vocabulary. The typings add TypeInfo.module? for this.

Why. @docx4j/generated-objects-ts will normalise WordprocessingML on save the way docx4j does (docx4j CR-060 and CR-061, for core-ts CR-015): colours written upper-case, values Word rejects omitted or written auto, and run-property elements without a valid value left out. Without these hooks that would mean editing the marshalled DOM by element names.

Cost. With neither callback set, the output is byte-identical and the marshal cost is unchanged. With callbacks that fall through at once, it is also within noise: 50,000 elements, median of seven runs, 230 to 236 ms against 3.7.0's 243 to 249 ms.

Also in this release: jsonix-CR-010 section 13 records that Boolean.parse and EnumLeafInfo.parse compare exactly, with no whitespace collapse and no case folding. onInvalidValue callers depend on this: Word reads " false" as on. Tests now pin it. There is no behaviour change.

What a consumer must do. Nothing.

Change request: docs/change-requests/jsonix-CR-011-marshal-side-adapters.md

3.7.0

Choose a tag to compare

@plutext plutext released this 23 Oct 23:09

One attribute value its type refuses no longer has to fail the whole unmarshal. Two per-call callbacks hand such a value to the caller instead:

context.createUnmarshaller({ onInvalidValue: function (text, propertyInfo, classInfo, node, error) { /* ... */ } })
context.createMarshaller({ onUnprintableValue: function (value, propertyInfo, classInfo, error) { /* ... */ } })

Unmarshal. onInvalidValue is called only after an attribute's value has failed its type's parse: a boolean outside true, 1, on, false, 0 and off, a value outside an enumeration, a number or date that does not parse.

  • A returned value is stored as the property's value, unchecked.
  • undefined or null leaves the property unset.
  • A throw aborts the unmarshal and is located with element, attribute and line, as today. Rethrowing error reproduces today's message exactly.

Marshal. onUnprintableValue is called when an attribute value fails its type's print, for example a string kept outside its enumeration. A returned string is written, and undefined or null omits the attribute.

Scope. The callbacks receive the class info, and classInfo.module.name names its module. A caller can therefore apply a rule to one vocabulary and rethrow everything else. In a WordprocessingML part, w: values can be read by Word's rules while the DrawingML inside stays strict. The runtime itself holds no Word rules.

Typings. Both callbacks are declared, and so are AttributePropertyInfo (typeInfo, attributeName, defaultValue), ClassInfo.module and TypeInfo.CLASS_NAME. TypeScript callers can dispatch on propertyInfo.typeInfo.name === 'Boolean' or on propertyInfo.typeInfo.CLASS_NAME === 'Jsonix.Model.EnumLeafInfo'.

Why. Word 365 opens documents holding values such as <w:b w:val="FALSE"/>, which it reads as on, and <w:u w:val="Single"/>, which it reads as unset. Until now one such value made @docx4j/generated-objects-ts and @docx4j/core-ts refuse the whole part, so nothing in it could be read.

What a consumer must do. Nothing. With neither callback set, behaviour, errors and output are unchanged.

Change request: docs/change-requests/jsonix-CR-010-invalid-attribute-values-to-the-caller.md

3.6.0

Choose a tag to compare

@plutext plutext released this 23 Oct 20:08

The context can now supply an attribute's schema default when the attribute is absent, as a JAXB getter does. The default comes from the context and is never written into the data.

context.getDefaultValue('org_docx4j_wml.BooleanDefaultTrue', 'val');   // true
context.valueOrDefault(b, 'val');                                       // b.val if present, else true

What it reads. jsonix-schema-compiler already copies each xsd attribute default into the mappings it generates (defaultValue, short dv). Until now the runtime ignored it.

  • getDefaultValue(typeName, propertyName) looks on the class info named typeName (what TYPE_NAME carries), then on its base types.
    • It returns undefined for an attribute without a default, for an element property, and for a property the type does not declare.
    • It throws when the context has no class info of that name.
  • valueOrDefault(object, propertyName, typeName?) returns the object's value when it exists (neither undefined nor null, the test marshal uses to write it). Otherwise it returns the default for typeName, or for the object's TYPE_NAME.
    • It throws when there is neither, and for an unknown type, whether or not the value is present.
  • Typings: valueOrDefault returns the property's declared type, so an optional property stays optional.

What does not change. Unmarshal results and marshal output are what 3.5.0 produces.

  • <w:b/> still unmarshals without a val key and marshals back as <w:b/>.
  • <w:b w:val="true"/> stays explicit.
  • Code that tests a property for undefined sees the same data.
  • Element defaults are not applied: XSD gives them to a present, empty element, never to an absent one.

Why. docx4j's isVal() returns true for <w:b/>; in the TypeScript model each consumer had to know that itself. docx4j audited wml.xsd's boolean defaults against ECMA-376 and Word first (docx4j #697 and CR-059), so a mapping generated from it now gives the right answer: a real default, false, or no default where the value is inherited (e.g. w:lsdException's locked from w:latentStyles).

What a consumer must do. Nothing. Nothing changes until something calls the new methods.

Change request: docs/change-requests/jsonix-CR-009-schema-defaults-on-read.md

3.5.0

Choose a tag to compare

@plutext plutext released this 20 Oct 04:00

The unmarshaller can now report, for each typed object, the source element it was read from. This is the counterpart of 3.4.0's marshal-side onElement.

context.createUnmarshaller({ onElement: function (element, value) { /* ... */ } })

When it fires. Once for every element read as a typed object, after the object is complete: its attributes and content are read and its PARENT is set. Children are therefore reported before their parent.

  • An xsi:type element is reported once, as its derived type.
  • element is the source node itself, in its own document, so lookupNamespaceURI sees its ancestors' declarations.

Not reported: elements holding a simple value (their owner is), { name, value } wrappers (their value is), and wildcard DOM content. The typings now promise that wildcard DOM content is the source node itself, not a copy. If unmarshalling throws, the calls already made stand.

Why. @docx4j/generated-objects-ts CR-011 records, for each typed mc:Choice, the bindings of the prefixes its Requires names. The typed tree keeps no namespace declarations, so those bindings are otherwise lost on a round trip.

What a consumer must do. Nothing: with the option unset, behaviour and output are unchanged, and the cost is not measurable. One edge: the option has the same name as the marshal-side callback. A caller that passes one options object to both createMarshaller and createUnmarshaller, or unmarshals from a context derived with onElement, now also gets unmarshal reports.

Change request: docs/change-requests/jsonix-CR-008-unmarshal-on-element.md

3.4.2

Choose a tag to compare

@plutext plutext released this 18 Oct 05:48

Three variables the runtime assigned without declaring are now declared. Under Node's CommonJS an undeclared assignment silently creates a global, but bundlers put the runtime inside an ES module, which is strict, and there it throws.

  • Base64Binary.decode (input): any xsd:base64Binary value threw input is not defined in strict mode, from a Vite or esbuild bundle or vitest's jsdom environment. In a Word document this means the VML v:shape of every text box, whose o:gfxdata is base64.
  • Unmarshaller.unmarshalFile and unmarshalURL (that): these also threw in strict mode. In sloppy mode that was a single global shared by overlapping calls.
  • Util.extend (sourceIsEvt): this was already declared in the npm copy. dist/Jsonix-all.js and the modular source now match it.

What a consumer must do. Nothing beyond taking 3.4.2: no API change, and a lockfile refresh is enough under ^3.4.0.

Guard. A new tests/strict.js scans all three copies of the runtime for assignments that resolve to no declaration, and loads the factory as strict code to run what threw. The whole suite also passes against a strict-mode copy of the factory.