TypeScript Generation#

The publish-ts command generates a typed Node 22-or-newer ESM source package. Install with --ignore-scripts and --no-package-lock, then run the package’s build script to create JavaScript and declaration files in dist. Use a prefixed install on POSIX; with npm 10 on Windows, run the install inside the generated package and retain the prefix only for the build. The exact platform commands and dry-pack check are documented in publish-ts.

Model mapping#

  • Item and composite type names remain PascalCase class names.

  • Property names become camelCase members. Their exact COGS names are retained as JSON and XML metadata.

  • COGS inheritance becomes TypeScript class inheritance; abstract model types are emitted as abstract classes.

  • Repeated and ordered properties use arrays.

  • ItemContainer, model classes, base classes, and specialized value helpers are exported from the package root.

Primitive mappings#

Strings/URIs use string. All numeric primitives use number under the shared integer, decimal and floating-point domains. DateTime uses Date normalized to UTC; date/time use strings to retain local calendar meaning and microseconds. Duration is a number of elapsed milliseconds. The wire representation of every temporal scalar remains a string.

Partial Gregorian helpers retain component information and nonzero Int32 years. CogsDate is an exactly-one-arm tagged union with native scalar payloads. See Native types and migration for all mappings and migration examples.

Serialization#

Generated values provide toObject/fromObject, toJson/fromJson, toElement/fromElement, and toXml/fromXml. ItemContainer also provides asynchronous path-or-Node-stream load* and dump* helpers.

Generated JSON supports ordinary JSON.parse and JSON.stringify. JSON.stringify(container) calls its wire-oriented toJSON method. The fromJson reader additionally rejects duplicate names and retains raw numeric tokens for exact domain checks and binary32 conversion. Use it for untrusted text; native JSON parsing has already discarded such evidence.

XML uses the model namespace, XSD element order, TypeOfObject references, xml:lang, and qualified xsi:type reusable substitutions. A per-container identity map makes repeated and forward references resolve to the same object. Synchronous DOM/string writers and asynchronous path/stream writers add the unqualified isReference="true" attribute to every top-level and item-property reference. Readers accept true, 1, and legacy absence, but reject false, qualified, or unknown reference attributes and markers on full items. The marker is not a generated TypeScript member.

The runtime rejects structural errors, duplicate or unknown content, missing/empty identity components, malformed primitive values, invalid discriminators, and duplicate definitions. Generated JSON Schema and XSD remain responsible for cardinality and model-specific facets.