@owsp/js

Runtime utilities for OpenWinSpec schemas: projection via x-partial, canonical stringification (4-decimal numbers), hashing, and validation helpers.

Quick usage

``ts
import {
listSerializeFields,
extractBySerializeGroup,
hashBySerializeGroup,
} from "@owsp/js";

const alias = "Material Profile System"; // schema title

// Inspect which fields participate in a group
const fields = listSerializeFields(alias, "summary");

// Build a projection and hash it deterministically
const projection = extractBySerializeGroup(alias, data, "summary");
const hash = hashBySerializeGroup(alias, data, "summary");
`

See docs: ../../docs/guide-x-partial.md.

Schema property ordering (x-order)

The package exposes helpers to order object properties according to x-order annotations in schemas. This is useful for stable serialization/UI forms.

APIs:

- Auto-detect schema and order:

`ts
import { orderObject } from "@owsp/js";

const ordered = orderObject(data);
`

- Order by bundle type (when known):

`ts
import { orderObjectByType, BundleType } from "@owsp/js";

const ordered = orderObjectByType(BundleType.MaterialSystem, data);
`

- Order by schema $id (internal tools):

`ts
import { orderObjectBySchemaId } from "@owsp/js";

const ordered = orderObjectBySchemaId(
"https://openwinspec.org/schemas/v1/material/profile/profile-system.json",
data
);
`

Details: ../../docs/schema-ordering.md.

Behavior notes:

- If some known properties have x-order, they come first by x-order value, then known properties without x-order (sorted by key), then unknown properties (sorted by key).
- If at a given object level none of the known properties have x-order, the original key order is preserved at that level; nested values are still processed recursively and may be ordered if their schemas specify x-order.

Build & test

`pwsh
nx build js
nx test js
`

Projection & Sorting Details

- Deep projection: extractBySerializeGroup() walks nested objects/arrays, resolving $ref, oneOf, and allOf to collect fields annotated with x-partial.
- Array sorting: If a schema property has x-partial.sortArrayBy: [key1, ...], arrays are sorted deterministically by these keys. Numeric keys sort ascending numerically; otherwise comparison falls back to canonical JSON strings.
- Post-projection sort: Arrays are re-sorted after projecting inner items to ensure final ordering matches sorting rules.
- Targeted fallback for glazing: For glazing assemblies, inner arrays glazings[].seals and glazings[].glazing_beads project as {vendor, id} when no x-partial fields are present, with thickness included when available. This avoids changing schema structure.
- Scope: The glazing fallback is deliberate and not applied to other assemblies (e.g., sash_seal). Behavior for other assemblies depends on their x-partial` annotations.