ng-form-foundry-transformers 0.2.1 → 0.3.0

package/README.md

@@ -69,9 +69,14 @@ const out = yamlTransformer.toSource({ ...initialValue, port: 9090 }, binding);
 //   port: 9090
 ```
 
-With a JSON Schema: `yamlTransformer.toSchema(yaml, { schema })` — `object` →
-nodeGroup, `array` of objects → nodeGroupList, scalar `enum` → enum leaf,
-`required`/`title`/`default` carried onto the leaves.
+With a JSON Schema: `yamlTransformer.toSchema(yaml, { schema })`. The mapping
+covers **draft 2020-12** (back-compatible with draft-07): `object` → nodeGroup (or
+a `map` for `additionalProperties`/`patternProperties`), `array` → nodeGroupList /
+leafList, `anyOf`/`oneOf` → choice (or a nullable leaf for `[T, null]`), `$ref` →
+`$defs`/`definitions` resolved inline (local **or cross-file** via
+`options.refDocuments`, matched by `$id`), `const` → a read-only leaf, and the string /
+number constraints (`pattern`, `minLength`, `minimum`, `multipleOf`, `format`, …)
+carried onto the leaves as validators.
 
 ## JSON transformer
 
@@ -176,10 +181,21 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.3.0` — data-integrity release plus JSON Schema draft 2020-12. Fixes three
+round-trip corruption bugs shipped in 0.2.1 (YAML maps with non-string keys
+duplicated entries; integers beyond 2^53 lost precision — now carried
+losslessly as strings, mirroring the YANG uint64 strategy; YANG identityref
+resolved to the wrong module on a local-name collision). `jsonSchemaToNodeGroup`
+grew from a draft-07 subset to draft 2020-12: `$ref`/`$defs`, cross-file `$ref`
+by `$id` (`refDocuments` option), `anyOf`/`oneOf` → choice, `type: [T, 'null']`
+→ nullable, `const` → read-only, `additionalProperties`/`patternProperties` →
+map, and string/number constraints as validators.
+
 `0.2.1` — first release under this name (formerly `yang-form-foundry`),
 restructured into a transformer catalog. YANG, YAML, and JSON transformers are
 complete; YAML and JSON share the format-agnostic form builders in `core` and are
-JSON-Schema-driven or inferred.
+JSON-Schema-driven or inferred. **Deprecated: contains the round-trip corruption
+bugs fixed in 0.3.0.**
 
 ## License
 

package/dist/core/bigint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Big-integer handling shared by the data transformers.
+ *
+ * JSON and YAML both write integers as bare numeric literals, but a JavaScript
+ * `number` only holds integers up to 2^53 − 1 exactly — parse `9007199254740993`
+ * and you get `…992` back. To avoid silently corrupting such values, the
+ * transformers carry any out-of-range integer as a **string** in the form value
+ * (the same strategy the YANG adapter uses for `int64`/`uint64`/`decimal64`) and
+ * re-emit it verbatim as an unquoted number. These helpers are the shared
+ * predicates for that path.
+ */
+/** A string that is a base-10 integer literal (optionally signed), safe or not. */
+export declare function isIntegerString(s: string): boolean;
+/** A BigInt whose magnitude exceeds the safe range, so a `number` can't hold it. */
+export declare function isUnsafeBigInt(b: bigint): boolean;
+/** An integer literal whose magnitude a `number` can't hold without loss. */
+export declare function isUnsafeIntegerString(s: string): boolean;

package/dist/core/bigint.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Big-integer handling shared by the data transformers.
+ *
+ * JSON and YAML both write integers as bare numeric literals, but a JavaScript
+ * `number` only holds integers up to 2^53 − 1 exactly — parse `9007199254740993`
+ * and you get `…992` back. To avoid silently corrupting such values, the
+ * transformers carry any out-of-range integer as a **string** in the form value
+ * (the same strategy the YANG adapter uses for `int64`/`uint64`/`decimal64`) and
+ * re-emit it verbatim as an unquoted number. These helpers are the shared
+ * predicates for that path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIntegerString = isIntegerString;
+exports.isUnsafeBigInt = isUnsafeBigInt;
+exports.isUnsafeIntegerString = isUnsafeIntegerString;
+/** Largest integer a `number` represents exactly (2^53 − 1), as a BigInt. */
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+/** A string that is a base-10 integer literal (optionally signed), safe or not. */
+function isIntegerString(s) {
+    return /^-?\d+$/.test(s);
+}
+/** A BigInt whose magnitude exceeds the safe range, so a `number` can't hold it. */
+function isUnsafeBigInt(b) {
+    return (b < 0n ? -b : b) > MAX_SAFE;
+}
+/** An integer literal whose magnitude a `number` can't hold without loss. */
+function isUnsafeIntegerString(s) {
+    return isIntegerString(s) && isUnsafeBigInt(BigInt(s));
+}

package/dist/core/index.d.ts

@@ -9,6 +9,6 @@ export type { Transformer, TransformResult, BindingMap } from './transformer';
 export { TransformerRegistry } from './registry';
 export { inferNodeGroup } from './infer';
 export { jsonSchemaToNodeGroup } from './json-schema';
-export type { JsonSchema } from './json-schema';
-export type { NodeGroup, NodeType, Leaf, LeafList, NodeGroupList, Choice, LeafType, FormValue, } from './schema';
+export type { JsonSchema, JsonSchemaOptions } from './json-schema';
+export type { NodeGroup, NodeType, Leaf, LeafList, NodeGroupList, Choice, ChoiceCase, NodeMap, LeafType, FormValue, } from './schema';
 export { CASE_KEY } from './schema';

package/dist/core/json-schema.d.ts

@@ -1,26 +1,65 @@
 import type { NodeGroup } from './schema';
 /**
- * The subset of JSON Schema (draft-07 style) this transformer maps to a form.
- * Only the keywords that shape a form are read; anything else is ignored. No
- * validation is performed — the schema drives *structure and types*, not
- * constraint checking (that stays server-side).
+ * The subset of JSON Schema (draft 2020-12, back-compatible with draft-07) this
+ * transformer maps to a form. Only the keywords that shape a form are read;
+ * anything else is ignored. The mapping drives *structure, types, and
+ * constraints*; the library turns the constraints into validators, but no
+ * validation happens here.
  */
 export interface JsonSchema {
+    $schema?: string;
+    $id?: string;
+    $ref?: string;
+    /** Draft 2020-12 reusable subschemas (draft-07 used `definitions`). */
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
     type?: JsonSchemaType | JsonSchemaType[];
     properties?: Record<string, JsonSchema>;
     required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    patternProperties?: Record<string, JsonSchema>;
     items?: JsonSchema;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
     enum?: unknown[];
+    const?: unknown;
     title?: string;
+    description?: string;
     default?: unknown;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    minProperties?: number;
+    maxProperties?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+/** Options for {@link jsonSchemaToNodeGroup}. */
+export interface JsonSchemaOptions {
+    /**
+     * Other schema documents a `$ref` may point at, matched by their `$id`. A
+     * cross-file ref like `/jsonschemas/common#/$defs/UeId` resolves into the
+     * document whose `$id` ends with `/jsonschemas/common`; refs *within* that
+     * document then resolve against it.
+     */
+    refDocuments?: JsonSchema[];
 }
 type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
 /**
  * Map a JSON Schema whose top level is an object into a root {@link NodeGroup}.
- * `object` → nodeGroup, `array` of objects → nodeGroupList, `array` of scalars →
- * leafList, a scalar with `enum` → enum leaf, other scalars → typed leaf.
- * `required` marks child leaves, `title` becomes the label, `default` carries a
- * scalar default.
+ *
+ * Supports draft 2020-12: local and cross-document `$ref` (see
+ * {@link JsonSchemaOptions.refDocuments}) are inline-resolved; `object` →
+ * nodeGroup (or a {@link NodeMap} when the keys are open via
+ * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
+ * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
+ * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
+ * number constraints) → a typed leaf. `required` marks child leaves, `title`
+ * becomes the label, `default`/`const` carry a scalar value.
  */
-export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string): NodeGroup;
+export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string, options?: JsonSchemaOptions): NodeGroup;
 export {};

package/dist/core/json-schema.js

@@ -4,54 +4,212 @@ exports.jsonSchemaToNodeGroup = jsonSchemaToNodeGroup;
 const ROOT = '__root__';
 /**
  * Map a JSON Schema whose top level is an object into a root {@link NodeGroup}.
- * `object` → nodeGroup, `array` of objects → nodeGroupList, `array` of scalars →
- * leafList, a scalar with `enum` → enum leaf, other scalars → typed leaf.
- * `required` marks child leaves, `title` becomes the label, `default` carries a
- * scalar default.
+ *
+ * Supports draft 2020-12: local and cross-document `$ref` (see
+ * {@link JsonSchemaOptions.refDocuments}) are inline-resolved; `object` →
+ * nodeGroup (or a {@link NodeMap} when the keys are open via
+ * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
+ * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
+ * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
+ * number constraints) → a typed leaf. `required` marks child leaves, `title`
+ * becomes the label, `default`/`const` carry a scalar value.
  */
-function jsonSchemaToNodeGroup(schema, name = ROOT) {
-    const group = objectToNodeGroup(schema, name, schema.title);
+function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
+    const documents = [schema, ...(options?.refDocuments ?? [])];
+    const resolver = new RefResolver(schema, documents);
+    const { schema: root, scope } = resolver.resolve(schema);
+    const group = objectToNodeGroup(root, name, scope, root.title);
     group.root = true;
     return group;
 }
-function objectToNodeGroup(schema, name, label) {
+/**
+ * Resolves `$ref` chains, following them across documents. A resolver is bound to
+ * one document (for `#/…` local refs); crossing into another document via a
+ * `<path>#/…` ref yields a resolver bound to *that* document, so the resolved
+ * schema's own local refs resolve correctly.
+ */
+class RefResolver {
+    constructor(doc, documents) {
+        this.doc = doc;
+        this.documents = documents;
+    }
+    resolve(schema) {
+        let current = schema;
+        let doc = this.doc;
+        const seen = new Set();
+        while (current && typeof current.$ref === 'string') {
+            const key = `${current.$ref}@${doc.$id ?? ''}`;
+            if (seen.has(key))
+                break; // cycle guard
+            seen.add(key);
+            const [docPath, fragment] = splitRef(current.$ref);
+            const targetDoc = docPath ? findDocument(this.documents, docPath) ?? doc : doc;
+            const target = resolveFragment(targetDoc, fragment);
+            if (!target)
+                break;
+            current = target;
+            doc = targetDoc;
+        }
+        return { schema: current, scope: doc === this.doc ? this : new RefResolver(doc, this.documents) };
+    }
+}
+/** Split a `$ref` into its document part (URI without fragment) and its fragment. */
+function splitRef(ref) {
+    const hash = ref.indexOf('#');
+    if (hash === -1)
+        return [ref || undefined, ''];
+    return [ref.slice(0, hash) || undefined, ref.slice(hash + 1)];
+}
+/** The document whose `$id` equals or ends with the ref's document path. */
+function findDocument(documents, docPath) {
+    return documents.find((d) => typeof d.$id === 'string' && (d.$id === docPath || d.$id.endsWith(docPath)));
+}
+/** Walk a JSON Pointer fragment (`/$defs/UeId`) within a document. */
+function resolveFragment(doc, fragment) {
+    if (!fragment || fragment === '/')
+        return doc;
+    let node = doc;
+    for (const raw of fragment.split('/')) {
+        if (raw === '')
+            continue;
+        const segment = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (node == null || typeof node !== 'object')
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+}
+// --- objects / maps -----------------------------------------------------------
+function objectToNodeGroup(schema, name, resolver, label) {
     const required = new Set(schema.required ?? []);
     const children = {};
     for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
-        children[key] = schemaToNode(key, propSchema, required.has(key));
+        children[key] = schemaToNode(key, propSchema, required.has(key), resolver);
     }
     const group = { kind: 'nodeGroup', name, children };
     if (label)
         group.label = label;
     return group;
 }
-function schemaToNode(name, schema, required) {
+/** An `object` with open keys — `additionalProperties: <schema>` or `patternProperties`, and no fixed `properties`. */
+function isOpenMap(schema) {
+    if (schema.properties && Object.keys(schema.properties).length)
+        return false;
+    const ap = schema.additionalProperties;
+    const additionalIsSchema = ap != null && typeof ap === 'object';
+    const hasPattern = !!schema.patternProperties && Object.keys(schema.patternProperties).length > 0;
+    return additionalIsSchema || hasPattern;
+}
+function objectToMap(name, schema, resolver) {
+    let valueSchema = {};
+    let keyPattern;
+    const pattern = schema.patternProperties && Object.entries(schema.patternProperties)[0];
+    if (pattern) {
+        [keyPattern, valueSchema] = pattern;
+    }
+    else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+        valueSchema = schema.additionalProperties;
+    }
+    const node = { kind: 'map', name, value: schemaToNode('value', valueSchema, false, resolver) };
+    if (schema.title)
+        node.label = schema.title;
+    if (keyPattern)
+        node.keyPattern = keyPattern;
+    if (typeof schema.minProperties === 'number')
+        node.minEntries = schema.minProperties;
+    if (typeof schema.maxProperties === 'number')
+        node.maxEntries = schema.maxProperties;
+    return node;
+}
+// --- anyOf / oneOf → choice ---------------------------------------------------
+/** The `anyOf`/`oneOf` `[T, null]` shape collapses to a nullable leaf; anything else is a choice. */
+function branchesToNode(name, schema, rawBranches, required, resolver) {
+    const branches = rawBranches.map((b) => resolver.resolve(b));
+    const nonNull = branches.filter((b) => b.schema.type !== 'null');
+    const sole = nonNull.length === 1 ? nonNull[0] : undefined;
+    if (sole && nonNull.length < branches.length && isScalarSchema(sole.schema)) {
+        const leaf = scalarLeaf(name, sole.schema, required);
+        leaf.nullable = true;
+        return leaf;
+    }
+    const cases = {};
+    const caseLabels = {};
+    branches.forEach(({ schema: branch, scope }, index) => {
+        const caseName = `case${index}`;
+        cases[caseName] = branchToCase(branch, scope);
+        if (branch.title)
+            caseLabels[caseName] = branch.title;
+    });
+    const choice = { kind: 'choice', name, cases };
+    if (schema.title)
+        choice.label = schema.title;
+    if (Object.keys(caseLabels).length)
+        choice.caseLabels = caseLabels;
+    return choice;
+}
+/** A resolved branch → a case body: a field record for an object branch, else a single node. */
+function branchToCase(branch, scope) {
+    if (primaryType(branch) === 'object' && branch.properties) {
+        const required = new Set(branch.required ?? []);
+        const fields = {};
+        for (const [key, propSchema] of Object.entries(branch.properties)) {
+            fields[key] = schemaToNode(key, propSchema, required.has(key), scope);
+        }
+        return fields;
+    }
+    return schemaToNode('value', branch, false, scope);
+}
+// --- dispatch -----------------------------------------------------------------
+function schemaToNode(name, rawSchema, required, resolver) {
+    const { schema, scope } = resolver.resolve(rawSchema);
+    const branches = schema.anyOf ?? schema.oneOf;
+    if (branches && branches.length) {
+        return branchesToNode(name, schema, branches, required, scope);
+    }
     const type = primaryType(schema);
-    if (type === 'object') {
-        return objectToNodeGroup(schema, name, schema.title);
+    if (type === 'object' || (type === undefined && (schema.properties || isOpenMap(schema)))) {
+        if (isOpenMap(schema))
+            return objectToMap(name, schema, scope);
+        return objectToNodeGroup(schema, name, scope, schema.title);
     }
     if (type === 'array') {
-        const items = schema.items ?? {};
-        if (primaryType(items) === 'object') {
+        const { schema: items, scope: itemScope } = scope.resolve(schema.items ?? {});
+        if (primaryType(items) === 'object' && items.properties) {
             const node = {
                 kind: 'nodeGroupList',
                 name,
-                type: objectToNodeGroup(items, name, items.title),
+                type: objectToNodeGroup(items, name, itemScope, items.title),
             };
             if (schema.title)
                 node.label = schema.title;
+            if (typeof schema.minItems === 'number')
+                node.minItems = schema.minItems;
+            if (typeof schema.maxItems === 'number')
+                node.maxItems = schema.maxItems;
             return node;
         }
         const list = { kind: 'leafList', name, type: scalarType(items) };
         if (schema.title)
             list.label = schema.title;
+        if (typeof schema.minItems === 'number')
+            list.minItems = schema.minItems;
+        if (typeof schema.maxItems === 'number')
+            list.maxItems = schema.maxItems;
         return list;
     }
-    // scalar leaf (possibly an enum)
+    return scalarLeaf(name, schema, required);
+}
+// --- scalar leaves ------------------------------------------------------------
+function scalarLeaf(name, schema, required) {
     const leaf = { kind: 'leaf', name, type: scalarType(schema) };
     if (schema.enum && schema.enum.length) {
         leaf.type = 'enum';
-        leaf.enum = schema.enum.filter((v) => typeof v === 'string' || typeof v === 'number');
+        leaf.enum = schema.enum.filter(isEnumMember);
+    }
+    // `const` — a fixed, read-only value.
+    if ('const' in schema && isScalar(schema.const)) {
+        leaf.default = schema.const;
+        leaf.readOnly = true;
     }
     if (required)
         leaf.required = true;
@@ -59,13 +217,41 @@ function schemaToNode(name, schema, required) {
         leaf.default = schema.default;
     if (schema.title)
         leaf.label = schema.title;
+    if (schema.description)
+        leaf.description = schema.description;
+    if (isNullable(schema))
+        leaf.nullable = true;
+    if (leaf.type === 'string') {
+        if (typeof schema.pattern === 'string')
+            leaf.pattern = schema.pattern;
+        if (typeof schema.minLength === 'number')
+            leaf.minLength = schema.minLength;
+        if (typeof schema.maxLength === 'number')
+            leaf.maxLength = schema.maxLength;
+        const format = mapFormat(schema.format);
+        if (format)
+            leaf.format = format;
+    }
+    else if (leaf.type === 'number') {
+        if (primaryType(schema) === 'integer')
+            leaf.integer = true;
+        if (typeof schema.minimum === 'number')
+            leaf.min = schema.minimum;
+        if (typeof schema.maximum === 'number')
+            leaf.max = schema.maximum;
+        if (typeof schema.multipleOf === 'number')
+            leaf.multipleOf = schema.multipleOf;
+    }
     return leaf;
 }
+// --- helpers ------------------------------------------------------------------
 /** The first declared type, ignoring a `null` companion in a `[T, 'null']` union. */
 function primaryType(schema) {
     const t = schema.type;
     if (Array.isArray(t))
         return t.find((x) => x !== 'null');
+    if (t === undefined && schema.const !== undefined)
+        return constType(schema.const);
     return t;
 }
 /** Map a JSON Schema scalar type to a form {@link LeafType} (default `string`). */
@@ -82,6 +268,33 @@ function scalarType(schema) {
             return 'string';
     }
 }
+function isScalarSchema(schema) {
+    const t = primaryType(schema);
+    return t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || (t === undefined && schema.enum != null);
+}
+function isNullable(schema) {
+    return Array.isArray(schema.type) && schema.type.includes('null');
+}
+function constType(value) {
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'string')
+        return 'string';
+    return undefined;
+}
+/** Map a JSON Schema `format` to the leaf formats the library validates. */
+function mapFormat(format) {
+    if (format === 'email' || format === 'idn-email')
+        return 'email';
+    if (format === 'uri' || format === 'iri' || format === 'url')
+        return 'uri';
+    return undefined;
+}
+function isEnumMember(v) {
+    return typeof v === 'string' || typeof v === 'number';
+}
 function isScalar(v) {
     return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
 }

package/dist/core/schema.d.ts

@@ -18,6 +18,27 @@ export interface Leaf {
     default?: string | number | boolean;
     /** Present when `type` is `'enum'`. */
     enum?: (string | number)[];
+    /** Display labels for the enum options, positionally aligned with `enum`. */
+    enumLabel?: string[];
+    /** Reject values not matching this regex (JSON Schema `pattern`; unanchored). */
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    /** Semantic string format (JSON Schema `format`). */
+    format?: 'email' | 'uri' | 'url';
+    /** Require a whole-number value (JSON Schema `type: 'integer'`). */
+    integer?: boolean;
+    /** Inclusive bounds (JSON Schema `minimum`/`maximum`). */
+    min?: number;
+    max?: number;
+    multipleOf?: number;
+    /** The value may be `null` (JSON Schema `type: [T, 'null']`). */
+    nullable?: boolean;
+    /** Optional scalar whose presence is itself data (on/off toggle). */
+    presence?: boolean;
+    /** Render read-only; with `default`, expresses a JSON Schema `const`. */
+    readOnly?: boolean;
+    description?: string;
 }
 export interface LeafList {
     kind: 'leafList';
@@ -48,21 +69,45 @@ export interface NodeGroupList {
     minItems?: number;
     maxItems?: number;
 }
+/** One case body: a record of named fields, or a single node (a leaf-bodied case). */
+export type ChoiceCase = Record<string, NodeType> | NodeType;
 /**
  * A discriminated selection: the user picks one `case`, and only that case's
  * fields are present. In the form value a choice is an object
  * `{ __case: <caseName>, ...that case's fields }`; the adapter flattens it to the
- * inline YANG encoding on write-back.
+ * inline YANG encoding on write-back. Cases may be anonymous/auto-named (from a
+ * JSON Schema `anyOf`/`oneOf`); the active case is inferred from seed data.
  */
 export interface Choice {
     kind: 'choice';
     name: string;
     label?: string;
-    cases: Record<string, Record<string, NodeType>>;
+    cases: Record<string, ChoiceCase>;
+    /** Display labels for cases, keyed by case name. */
+    caseLabels?: Record<string, string>;
     default?: string;
     mandatory?: boolean;
 }
-export type NodeType = Leaf | LeafList | NodeGroup | NodeGroupList | Choice;
+/**
+ * An open, arbitrary-keyed record: unlike {@link NodeGroup} (a fixed key set), a
+ * map's keys are runtime data and every value conforms to one `value` schema.
+ * Maps JSON Schema `additionalProperties: <schema>` / `patternProperties`.
+ */
+export interface NodeMap {
+    kind: 'map';
+    name: string;
+    label?: string;
+    description?: string;
+    /** The schema every entry's value conforms to. */
+    value: NodeType;
+    keyLabel?: string;
+    /** `patternProperties`: entry keys must match this regex. */
+    keyPattern?: string;
+    minEntries?: number;
+    maxEntries?: number;
+    presence?: boolean;
+}
+export type NodeType = Leaf | LeafList | NodeGroup | NodeGroupList | Choice | NodeMap;
 /** The form-value key that records which case of a {@link Choice} is active. */
 export declare const CASE_KEY = "__case";
 /** A plain, nested value object produced/consumed by a rendered form. */

package/dist/transformers/json/json-transformer.d.ts

@@ -17,6 +17,12 @@ export interface JsonFormat {
     indent: number;
     /** Whether the source ended with a trailing newline. */
     trailingNewline: boolean;
+    /**
+     * Paths (as `JSON.stringify`'d key/index arrays) that held an integer literal
+     * too large for a JS `number`. Their form value is a string; `toSource` emits
+     * them back as unquoted numbers so precision survives the round-trip.
+     */
+    bigInts: string[];
 }
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
@@ -30,6 +36,10 @@ export interface JsonFormat {
  * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
  * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
  * instead — `JSON.parse` rejects comments.
+ *
+ * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
+ * as strings in the form value and re-emitted verbatim as unquoted numbers (the
+ * same strategy the YANG adapter uses for `uint64`).
  */
 export declare const jsonTransformer: {
     id: string;

package/dist/transformers/json/json-transformer.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonTransformer = void 0;
 const infer_1 = require("../../core/infer");
 const json_schema_1 = require("../../core/json-schema");
+const bigint_1 = require("../../core/bigint");
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
  * the edited value back to JSON. The form is built by the same format-agnostic
@@ -15,22 +16,33 @@ const json_schema_1 = require("../../core/json-schema");
  * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
  * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
  * instead — `JSON.parse` rejects comments.
+ *
+ * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
+ * as strings in the form value and re-emitted verbatim as unquoted numbers (the
+ * same strategy the YANG adapter uses for `uint64`).
  */
 exports.jsonTransformer = {
     id: 'json',
     toSchema(source, options) {
-        const data = (JSON.parse(source) ?? {});
+        const bigInts = [];
+        const parsed = JSON.parse(source, bigIntReviver);
+        const data = collectBigInts(parsed ?? {}, [], bigInts);
         const schema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
         const binding = {
             indent: detectIndent(source),
             trailingNewline: source.endsWith('\n'),
+            bigInts,
         };
         return { schema, binding, initialValue: data };
     },
     toSource(value, binding) {
-        const text = JSON.stringify(value, null, binding.indent);
+        const paths = new Set(binding.bigInts);
+        const prepared = paths.size ? markBigInts(value, [], paths) : value;
+        let text = JSON.stringify(prepared, null, binding.indent);
+        if (paths.size)
+            text = text.replace(BIGINT_MARK_RE, '$1');
         return binding.trailingNewline ? text + '\n' : text;
     },
 };
@@ -39,3 +51,81 @@ function detectIndent(source) {
     const match = source.match(/\n( +)\S/);
     return match && match[1] ? match[1].length : 2;
 }
+// --- big-integer preservation -------------------------------------------------
+/** A key/index path key, collision-free across separator characters. */
+function pathKey(path) {
+    return JSON.stringify(path);
+}
+/** Placeholder wrapping a big-int value through `JSON.stringify`, stripped after. */
+const BIGINT_MARK = '@@nff-bigint@@';
+const BIGINT_MARK_RE = new RegExp(`"${BIGINT_MARK}(-?\\d+)${BIGINT_MARK}"`, 'g');
+/** An out-of-range integer literal, captured verbatim from the source. */
+class BigIntLiteral {
+    constructor(digits) {
+        this.digits = digits;
+    }
+}
+/**
+ * A `JSON.parse` reviver that captures integer literals too large for a `number`.
+ * The parsed `value` is already lossy, so the exact digits come from the reviver
+ * `context.source` (the raw literal text; available on Node 21+). Genuine strings
+ * never reach here as numbers, so a quoted big-digit value stays a plain string.
+ *
+ * On a runtime without `context.source` (Node < 21) the exact digits can't be
+ * recovered, so an out-of-range integer throws with an actionable message rather
+ * than being silently rounded. Safe integers and floats are unaffected there.
+ */
+function bigIntReviver(_key, value, context) {
+    if (typeof value !== 'number')
+        return value;
+    if (context && typeof context.source === 'string') {
+        return (0, bigint_1.isUnsafeIntegerString)(context.source) ? new BigIntLiteral(context.source) : value;
+    }
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+        throw new RangeError(`JSON integer ${value} exceeds the safe range (2^53) and its exact value cannot be ` +
+            `recovered on this runtime. Use Node ≥ 21 for lossless big-integer support, or ` +
+            `quote the value as a string in the source.`);
+    }
+    return value;
+}
+/**
+ * Replace each {@link BigIntLiteral} with its digit string in the form value, and
+ * record its path so `toSource` can re-emit it unquoted. Walks objects and arrays.
+ */
+function collectBigInts(node, path, out) {
+    if (node instanceof BigIntLiteral) {
+        out.push(pathKey(path));
+        return node.digits;
+    }
+    if (Array.isArray(node))
+        return node.map((v, i) => collectBigInts(v, [...path, i], out));
+    if (isPlainObject(node)) {
+        const res = {};
+        for (const key of Object.keys(node))
+            res[key] = collectBigInts(node[key], [...path, key], out);
+        return res;
+    }
+    return node;
+}
+/**
+ * Wrap the string value at each recorded big-int path in a placeholder so
+ * `JSON.stringify` emits it as a (quoted) string that {@link BIGINT_MARK_RE} then
+ * unquotes. A value the user has edited to a non-integer stays a normal string.
+ */
+function markBigInts(node, path, paths) {
+    if (typeof node === 'string') {
+        return paths.has(pathKey(path)) && (0, bigint_1.isIntegerString)(node) ? `${BIGINT_MARK}${node}${BIGINT_MARK}` : node;
+    }
+    if (Array.isArray(node))
+        return node.map((v, i) => markBigInts(v, [...path, i], paths));
+    if (isPlainObject(node)) {
+        const res = {};
+        for (const key of Object.keys(node))
+            res[key] = markBigInts(node[key], [...path, key], paths);
+        return res;
+    }
+    return node;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/transformers/yaml/revert.d.ts

@@ -9,5 +9,10 @@ import { type Document } from 'yaml';
  * comments. Counterpart of the schema/inference in {@link import('./infer')} and
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
+ *
+ * Map keys are matched by the *same string form* `doc.toJS()` produced when the
+ * form value was built, so non-string keys (a `80:` port map, a `true:` flag)
+ * reconcile against their original typed key nodes instead of being appended as
+ * duplicate string-keyed pairs.
  */
 export declare function applyValueToDocument(doc: Document, value: unknown): void;

package/dist/transformers/yaml/revert.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyValueToDocument = applyValueToDocument;
 const yaml_1 = require("yaml");
+const bigint_1 = require("../../core/bigint");
 /**
  * Apply an edited form value onto a parsed YAML {@link Document} in place,
  * preserving comments and formatting on every node that survives the edit.
@@ -12,62 +13,97 @@ const yaml_1 = require("yaml");
  * comments. Counterpart of the schema/inference in {@link import('./infer')} and
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
+ *
+ * Map keys are matched by the *same string form* `doc.toJS()` produced when the
+ * form value was built, so non-string keys (a `80:` port map, a `true:` flag)
+ * reconcile against their original typed key nodes instead of being appended as
+ * duplicate string-keyed pairs.
  */
 function applyValueToDocument(doc, value) {
     if (doc.contents == null) {
         doc.contents = doc.createNode(value);
         return;
     }
-    applyAt(doc, [], value);
+    doc.contents = applyToNode(doc, doc.contents, value);
 }
-function applyAt(doc, path, value) {
-    const node = nodeAt(doc, path);
+/**
+ * Reconcile the parsed `node` at one position with its edited `value`, returning
+ * the node to store there. A scalar is mutated in place so its comments survive;
+ * a map/sequence is reconciled child-by-child; a shape change (or a brand-new
+ * position) allocates a fresh node.
+ */
+function applyToNode(doc, node, value) {
     if (isPlainObject(value)) {
         if (!(0, yaml_1.isMap)(node))
-            return replaceAt(doc, path, value);
-        const keys = new Set(Object.keys(value));
-        for (const key of mapKeyStrings(node)) {
-            if (!keys.has(key))
-                node.delete(key);
-        }
-        for (const key of keys)
-            applyAt(doc, [...path, key], value[key]);
-        return;
+            return doc.createNode(value);
+        reconcileMap(doc, node, value);
+        return node;
     }
     if (Array.isArray(value)) {
         if (!(0, yaml_1.isSeq)(node))
-            return replaceAt(doc, path, value);
-        while (node.items.length > value.length)
-            node.items.pop();
-        for (let i = 0; i < value.length; i++) {
-            if (i < node.items.length)
-                applyAt(doc, [...path, i], value[i]);
-            else
-                node.items.push(doc.createNode(value[i]));
-        }
-        return;
+            return doc.createNode(value);
+        reconcileSeq(doc, node, value);
+        return node;
     }
     // scalar (string / number / boolean / null)
-    if ((0, yaml_1.isScalar)(node))
-        node.value = value;
-    else
-        replaceAt(doc, path, value);
+    if ((0, yaml_1.isScalar)(node)) {
+        node.value = coerceScalarValue(value, node.value);
+        return node;
+    }
+    return doc.createNode(value);
 }
-/** Set the whole subtree at `path` to a fresh node (used when the shape changed). */
-function replaceAt(doc, path, value) {
-    if (path.length === 0) {
-        doc.contents = doc.createNode(value);
+/**
+ * Update a map node against the value object: drop pairs whose key is gone,
+ * recurse into the ones that remain (matched by their `toJS` key string, so
+ * typed keys line up), and append a fresh pair for each genuinely new key.
+ */
+function reconcileMap(doc, node, value) {
+    node.items = node.items.filter((pair) => keyString(pair.key) in value);
+    for (const key of Object.keys(value)) {
+        const pair = node.items.find((p) => keyString(p.key) === key);
+        if (pair) {
+            pair.value = applyToNode(doc, pair.value, value[key]);
+        }
+        else {
+            node.items.push(doc.createPair(key, value[key]));
+        }
     }
-    else {
-        doc.setIn(path, doc.createNode(value));
+}
+/** Update a sequence node: shrink/grow to the value's length, recurse per item. */
+function reconcileSeq(doc, node, value) {
+    while (node.items.length > value.length)
+        node.items.pop();
+    for (let i = 0; i < value.length; i++) {
+        if (i < node.items.length) {
+            node.items[i] = applyToNode(doc, node.items[i], value[i]);
+        }
+        else {
+            node.items.push(doc.createNode(value[i]));
+        }
     }
 }
-function nodeAt(doc, path) {
-    return path.length === 0 ? doc.contents : doc.getIn(path, true);
+/**
+ * The value to store on a scalar node. An out-of-range integer is carried in the
+ * form value as a string (a `number` would lose precision); when the node it
+ * lands on already held a BigInt — i.e. the source had an unquoted integer there
+ * — restore the BigInt so it re-emits as a bare number rather than a quoted
+ * string. Everything else passes through unchanged (a genuine string key stays a
+ * string node, so it keeps its quotes).
+ */
+function coerceScalarValue(value, current) {
+    if (typeof current === 'bigint' && typeof value === 'string' && (0, bigint_1.isIntegerString)(value)) {
+        return BigInt(value);
+    }
+    return value;
 }
-/** The string keys currently present in a YAML map node. */
-function mapKeyStrings(node) {
-    return node.items.map((pair) => ((0, yaml_1.isScalar)(pair.key) ? String(pair.key.value) : String(pair.key)));
+/**
+ * The string a key node takes as a JS object key, matching `doc.toJS()`: the
+ * scalar value stringified, with `null`/`undefined` collapsing to `''` (the
+ * empty key `toJS` uses for a `null:` key).
+ */
+function keyString(key) {
+    const v = (0, yaml_1.isScalar)(key) ? key.value : key;
+    return v == null ? '' : String(v);
 }
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);

package/dist/transformers/yaml/yaml-transformer.js

@@ -4,6 +4,7 @@ exports.yamlTransformer = void 0;
 const yaml_1 = require("yaml");
 const infer_1 = require("../../core/infer");
 const json_schema_1 = require("../../core/json-schema");
+const bigint_1 = require("../../core/bigint");
 const revert_1 = require("./revert");
 /**
  * A YAML {@link Transformer}: turn a YAML config document into a form and write
@@ -20,8 +21,11 @@ const revert_1 = require("./revert");
 exports.yamlTransformer = {
     id: 'yaml',
     toSchema(source, options) {
-        const doc = (0, yaml_1.parseDocument)(source);
-        const data = (doc.toJS() ?? {});
+        // Parse integers as BigInt so the document nodes keep full precision; the
+        // revert re-emits them verbatim. The form value can't carry a BigInt, so
+        // out-of-range integers become strings there (safe ones become plain numbers).
+        const doc = (0, yaml_1.parseDocument)(source, { intAsBigInt: true });
+        const data = (normalizeBigInts(doc.toJS()) ?? {});
         const schema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
@@ -35,3 +39,21 @@ exports.yamlTransformer = {
     // `satisfies` verifies conformance to the catalog contract while keeping the
     // concrete sync return types, so direct callers need no `await`.
 };
+/**
+ * Replace every BigInt from an `intAsBigInt` parse with a form-value scalar: a
+ * plain `number` when it fits the safe range, otherwise its decimal string (so
+ * precision survives). Walks maps and sequences; leaves other values untouched.
+ */
+function normalizeBigInts(value) {
+    if (typeof value === 'bigint')
+        return (0, bigint_1.isUnsafeBigInt)(value) ? value.toString() : Number(value);
+    if (Array.isArray(value))
+        return value.map(normalizeBigInts);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value))
+            out[key] = normalizeBigInts(value[key]);
+        return out;
+    }
+    return value;
+}

package/dist/transformers/yang/mapper.js

@@ -42,7 +42,8 @@ function mapNode(node) {
                 leaf.required = true;
             if (node.default !== undefined)
                 leaf.default = node.default;
-            const options = node.type.enums ?? node.type.identities?.map((i) => i.name);
+            const identities = node.type.identities;
+            const options = node.type.enums ?? identities?.map((i) => (0, rfc7951_1.identityToken)(i.module, i.name, identities));
             if (options)
                 leaf.enum = [...options];
             return leaf;

package/dist/transformers/yang/revert.js

@@ -88,7 +88,7 @@ function decodeLeaf(node, raw) {
             return group;
         }
         case 'identityref':
-            return typeof raw === 'string' ? (0, rfc7951_1.bareIdentity)(raw) : raw;
+            return typeof raw === 'string' ? (0, rfc7951_1.wireToFormIdentity)(raw, node.module, node.type) : raw;
         default:
             return raw;
     }

package/dist/transformers/yang/rfc7951.d.ts

@@ -17,14 +17,32 @@ export declare function isStringEncoded(base: YangBase): boolean;
  * so it never reaches this function.
  */
 export declare function toFormLeafType(t: YangType): LeafType;
+type Identity = {
+    name: string;
+    module: string;
+};
+/**
+ * The token an identityref takes in the *form* (dropdown option and form value):
+ * the bare identity name, or a fully-qualified `module:name` when the bare name
+ * is ambiguous — the same local name is derived from more than one module.
+ * Keeping ambiguous identities qualified lets {@link qualifyIdentity} recover the
+ * exact identity on write-back; unambiguous ones stay bare for a clean UI.
+ */
+export declare function identityToken(module: string, name: string, identities: Identity[]): string;
+/**
+ * Resolve an RFC 7951 identityref *wire* value to its form {@link identityToken}.
+ * A qualified `module:name` names that exact identity; a bare name is an identity
+ * in the leaf's own module (RFC 7951 §6.8).
+ */
+export declare function wireToFormIdentity(wire: string, leafModule: string, t: YangType): string;
 /**
  * RFC 7951 identityref value (§6.8): `module:identity` when the identity is
  * defined in a different module than the referencing leaf, otherwise the bare
- * identity name.
+ * identity name. The incoming `token` is the form value — bare, or `module:name`
+ * when the local name is ambiguous (see {@link identityToken}) — so the exact
+ * identity is recovered even when two modules derive the same name.
  */
-export declare function qualifyIdentity(name: string, leafModule: string, t: YangType): string;
-/** The local identity name, dropping any `module:` prefix. */
-export declare function bareIdentity(value: string): string;
+export declare function qualifyIdentity(token: string, leafModule: string, t: YangType): string;
 /**
  * RFC 7951 member name for a node (§4). A name is qualified `module:name` when
  * the node is at the top level (no parent module) or its module differs from its
@@ -36,3 +54,4 @@ export declare function splitQualified(member: string): {
     module?: string;
     name: string;
 };
+export {};

package/dist/transformers/yang/rfc7951.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isStringEncoded = isStringEncoded;
 exports.toFormLeafType = toFormLeafType;
+exports.identityToken = identityToken;
+exports.wireToFormIdentity = wireToFormIdentity;
 exports.qualifyIdentity = qualifyIdentity;
-exports.bareIdentity = bareIdentity;
 exports.qualifiedName = qualifiedName;
 exports.splitQualified = splitQualified;
 /**
@@ -51,19 +52,54 @@ function toFormLeafType(t) {
         return 'number';
     return 'string';
 }
+/** True when more than one derived identity shares this local name. */
+function nameIsAmbiguous(identities, name) {
+    return identities.filter((i) => i.name === name).length > 1;
+}
+/**
+ * The token an identityref takes in the *form* (dropdown option and form value):
+ * the bare identity name, or a fully-qualified `module:name` when the bare name
+ * is ambiguous — the same local name is derived from more than one module.
+ * Keeping ambiguous identities qualified lets {@link qualifyIdentity} recover the
+ * exact identity on write-back; unambiguous ones stay bare for a clean UI.
+ */
+function identityToken(module, name, identities) {
+    return nameIsAmbiguous(identities, name) ? `${module}:${name}` : name;
+}
+/**
+ * Resolve an RFC 7951 identityref *wire* value to its form {@link identityToken}.
+ * A qualified `module:name` names that exact identity; a bare name is an identity
+ * in the leaf's own module (RFC 7951 §6.8).
+ */
+function wireToFormIdentity(wire, leafModule, t) {
+    const identities = t.identities ?? [];
+    const id = resolveIdentity(wire, leafModule, identities);
+    return id ? identityToken(id.module, id.name, identities) : splitQualified(wire).name;
+}
 /**
  * RFC 7951 identityref value (§6.8): `module:identity` when the identity is
  * defined in a different module than the referencing leaf, otherwise the bare
- * identity name.
+ * identity name. The incoming `token` is the form value — bare, or `module:name`
+ * when the local name is ambiguous (see {@link identityToken}) — so the exact
+ * identity is recovered even when two modules derive the same name.
  */
-function qualifyIdentity(name, leafModule, t) {
-    const id = t.identities?.find((i) => i.name === name);
-    return id && id.module !== leafModule ? `${id.module}:${name}` : name;
+function qualifyIdentity(token, leafModule, t) {
+    const identities = t.identities ?? [];
+    const { module, name } = splitQualified(token);
+    const id = resolveIdentity(token, leafModule, identities);
+    const idModule = id ? id.module : module ?? leafModule;
+    return idModule !== leafModule ? `${idModule}:${name}` : name;
 }
-/** The local identity name, dropping any `module:` prefix. */
-function bareIdentity(value) {
-    const i = value.indexOf(':');
-    return i === -1 ? value : value.slice(i + 1);
+/**
+ * The specific identity a bare-or-qualified reference points at: matched on
+ * module + name when qualified (or when the leaf's own module has that name),
+ * else the first identity with that local name.
+ */
+function resolveIdentity(ref, leafModule, identities) {
+    const { module, name } = splitQualified(ref);
+    const owner = module ?? leafModule;
+    return identities.find((i) => i.name === name && i.module === owner)
+        ?? identities.find((i) => i.name === name);
 }
 /**
  * RFC 7951 member name for a node (§4). A name is qualified `module:name` when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Framework-agnostic Node + TypeScript catalog of source-format transformers: turn a YANG model (and more) into an ng-form-foundry schema and revert the edited form value back to the source format.",
   "keywords": [
     "ng-form-foundry",