ng-form-foundry-transformers 0.5.0 → 0.5.2

package/dist/transformers/yaml/revert.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyValueToDocument = applyValueToDocument;
 const yaml_1 = require("yaml");
 const bigint_1 = require("../../core/bigint");
+const schema_keys_1 = require("../../core/schema-keys");
 /**
  * Apply an edited form value onto a parsed YAML {@link Document} in place,
  * preserving comments and formatting on every node that survives the edit.
@@ -14,17 +15,23 @@ const bigint_1 = require("../../core/bigint");
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
  *
+ * With `schema` (the NodeGroup the form was built from) the
+ * value is authoritative for **schema-born paths only**: keys the schema does
+ * not cover — at any depth — are preserved verbatim, their comments included.
+ * Without it the value covers the whole document and a key it lacks is a
+ * deletion.
+ *
  * 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) {
+function applyValueToDocument(doc, value, schema) {
     if (doc.contents == null) {
         doc.contents = doc.createNode(value);
         return;
     }
-    doc.contents = applyToNode(doc, doc.contents, value);
+    doc.contents = applyToNode(doc, doc.contents, value, schema);
 }
 /**
  * Reconcile the parsed `node` at one position with its edited `value`, returning
@@ -32,22 +39,27 @@ function applyValueToDocument(doc, value) {
  * 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) {
+function applyToNode(doc, node, value, schema) {
     if (isPlainObject(value)) {
         if (!(0, yaml_1.isMap)(node))
             return doc.createNode(value);
-        reconcileMap(doc, node, value);
+        reconcileMap(doc, node, value, schema && (0, schema_keys_1.childrenOf)(schema));
         return node;
     }
     if (Array.isArray(value)) {
         if (!(0, yaml_1.isSeq)(node))
             return doc.createNode(value);
-        reconcileSeq(doc, node, value);
+        reconcileSeq(doc, node, value, (0, schema_keys_1.itemSchemaOf)(schema));
         return node;
     }
     // scalar (string / number / boolean / null)
     if ((0, yaml_1.isScalar)(node)) {
-        node.value = coerceScalarValue(value, node.value);
+        const next = coerceScalarValue(value, node.value);
+        // An unchanged value keeps the node untouched — the parsed BigInt and the
+        // form's number compare by numeric value, so an identity pass never
+        // downgrades a BigInt-held integer to a lossy JS number.
+        if (!sameScalar(node.value, next))
+            node.value = next;
         return node;
     }
     return doc.createNode(value);
@@ -56,13 +68,24 @@ function applyToNode(doc, node, 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.
+ * Under `schema`, keys that are not schema-born are exempt from all three —
+ * never dropped, never recursed into, never addable.
  */
-function reconcileMap(doc, node, value) {
-    node.items = node.items.filter((pair) => keyString(pair.key) in value);
+function reconcileMap(doc, node, value, schema) {
+    node.items = node.items.filter((pair) => {
+        const key = keyString(pair.key);
+        if (schema && !schema.has(key))
+            return true; // not schema-born: verbatim
+        // Own-key check: `in` would resolve doc keys like `toString` through the
+        // prototype chain and make them undeletable.
+        return Object.prototype.hasOwnProperty.call(value, key);
+    });
     for (const key of Object.keys(value)) {
+        if (schema && !schema.has(key))
+            continue; // not schema-born: never written
         const pair = node.items.find((p) => keyString(p.key) === key);
         if (pair) {
-            pair.value = applyToNode(doc, pair.value, value[key]);
+            pair.value = applyToNode(doc, pair.value, value[key], schema?.get(key));
         }
         else {
             node.items.push(doc.createPair(key, value[key]));
@@ -70,12 +93,12 @@ function reconcileMap(doc, node, value) {
     }
 }
 /** Update a sequence node: shrink/grow to the value's length, recurse per item. */
-function reconcileSeq(doc, node, value) {
+function reconcileSeq(doc, node, value, itemSchema) {
     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]);
+            node.items[i] = applyToNode(doc, node.items[i], value[i], itemSchema);
         }
         else {
             node.items.push(doc.createNode(value[i]));
@@ -96,6 +119,15 @@ function coerceScalarValue(value, current) {
     }
     return value;
 }
+/** Numeric equality across the BigInt/number divide, `===` otherwise. */
+function sameScalar(current, next) {
+    if (current === next)
+        return true;
+    if (typeof current === 'bigint' && typeof next === 'number' && Number.isInteger(next)) {
+        return current === BigInt(next);
+    }
+    return false;
+}
 /**
  * The string a key node takes as a JS object key, matching `doc.toJS()`: the
  * scalar value stringified, with `null`/`undefined` collapsing to `''` (the

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

@@ -1,5 +1,5 @@
 import { type Document } from 'yaml';
-import type { FormValue, Thesaurus } from '../../core/schema';
+import type { FormValue, NodeGroup, Thesaurus } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
 import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link yamlTransformer}'s `toSchema`. */
@@ -21,6 +21,32 @@ export interface YamlOptions {
      * case-insensitively; never paths.
      */
     thesaurus?: Thesaurus;
+    /**
+     * Schema-driven mode only: what happens to keys the JSON Schema does not
+     * cover. `'preserve'` (default) keeps them verbatim — the form never
+     * carried them, so a partial schema edits its slice without erasing the
+     * rest. `'drop'` makes the edited value authoritative for the whole
+     * document, deleting uncovered keys — for consumers whose schema is
+     * intentionally complete. `'edit'` surfaces them instead: uncovered keys
+     * render as editable fields typed by the data (the inferred schema merged
+     * under the JSON Schema), so nothing is invisible and the value covers the
+     * whole document. Ignored without a `schema`.
+     */
+    unknownKeys?: 'preserve' | 'drop' | 'edit';
+}
+/**
+ * The revert context: the parsed {@link Document} and — in schema-driven
+ * mode with `unknownKeys: 'preserve'` or `'edit'` — the NodeGroup the form
+ * was built from (the JSON Schema's own under `'preserve'`, the
+ * inferred-merged one under `'edit'`), so `toSource` treats the value as
+ * authoritative for schema-born paths only. Under `'edit'` that is almost
+ * the whole document; the gate still protects the keys no form field can
+ * carry (e.g. a key inside a covered choice's object that no case names).
+ * Treat it as opaque: build it with `toSchema`, hand it back to `toSource`.
+ */
+export interface YamlBinding {
+    doc: Document;
+    schema?: NodeGroup;
 }
 /**
  * A YAML {@link Transformer}: turn a YAML config document into a form and write
@@ -28,14 +54,15 @@ export interface YamlOptions {
  * preserves comments, key order, and formatting by applying edits onto the parsed
  * document (see {@link applyValueToDocument}).
  *
- * The `binding` it round-trips is the parsed {@link Document}; `toSource` clones
- * it before applying, so a single `toSchema` result can serve many edits.
+ * The `binding` it round-trips is a {@link YamlBinding}; `toSource` clones the
+ * document inside it before applying, so a single `toSchema` result can serve
+ * many edits.
  *
  * With a JSON Schema in {@link YamlOptions}, the form is schema-driven; without
  * one it is inferred from the data.
  */
 export declare const yamlTransformer: {
     id: string;
-    toSchema(source: string, options?: YamlOptions): TransformResult<Document>;
-    toSource(value: FormValue, binding: Document): string;
+    toSchema(source: string, options?: YamlOptions): TransformResult<YamlBinding>;
+    toSource(value: FormValue, binding: YamlBinding): string;
 };

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

@@ -5,6 +5,9 @@ const yaml_1 = require("yaml");
 const thesaurus_1 = require("../../core/thesaurus");
 const infer_1 = require("../../core/infer");
 const json_schema_1 = require("../../core/json-schema");
+const merge_inferred_1 = require("../../core/merge-inferred");
+const schema_keys_1 = require("../../core/schema-keys");
+const shape_check_1 = require("../../core/shape-check");
 const bigint_1 = require("../../core/bigint");
 const revert_1 = require("./revert");
 /**
@@ -13,8 +16,9 @@ const revert_1 = require("./revert");
  * preserves comments, key order, and formatting by applying edits onto the parsed
  * document (see {@link applyValueToDocument}).
  *
- * The `binding` it round-trips is the parsed {@link Document}; `toSource` clones
- * it before applying, so a single `toSchema` result can serve many edits.
+ * The `binding` it round-trips is a {@link YamlBinding}; `toSource` clones the
+ * document inside it before applying, so a single `toSchema` result can serve
+ * many edits.
  *
  * With a JSON Schema in {@link YamlOptions}, the form is schema-driven; without
  * one it is inferred from the data.
@@ -27,17 +31,36 @@ exports.yamlTransformer = {
         // 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
+        const unknownKeys = options?.unknownKeys ?? 'preserve';
+        const fromJsonSchema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
-            : (0, infer_1.inferNodeGroup)(data, options?.rootName);
-        if (!options?.schema && doc.contents)
+            : undefined;
+        const schema = fromJsonSchema && unknownKeys === 'edit'
+            ? (0, merge_inferred_1.mergeInferred)(fromJsonSchema, (0, infer_1.inferNodeGroup)(data, options?.rootName))
+            : fromJsonSchema ?? (0, infer_1.inferNodeGroup)(data, options?.rootName);
+        // A container-shape disagreement between document and schema would erase
+        // the section on save: refuse up front (see assertSchemaShapes).
+        if (fromJsonSchema)
+            (0, shape_check_1.assertSchemaShapes)(data, fromJsonSchema);
+        // Every mode picks up the document's hex/octal presentation: inference
+        // for its own leaves, schema-driven leaves too — the JSON Schema cannot
+        // know the base a value was written in, the document does.
+        if (doc.contents)
             annotateRadix(doc.contents, schema);
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
-        return { schema: labeled, binding: doc, initialValue: data };
+        return {
+            schema: labeled,
+            // 'preserve' gates the revert on the JSON Schema's NodeGroup; 'edit' on
+            // the merged one (schema-born ≈ everything, but keys no form field can
+            // carry stay protected); 'drop' and inferred mode leave the value
+            // authoritative for the whole document.
+            binding: { doc, schema: fromJsonSchema && unknownKeys !== 'drop' ? schema : undefined },
+            initialValue: data,
+        };
     },
     toSource(value, binding) {
-        const doc = binding.clone();
-        (0, revert_1.applyValueToDocument)(doc, value);
+        const doc = binding.doc.clone();
+        (0, revert_1.applyValueToDocument)(doc, value, binding.schema);
         return String(doc);
     },
     // `satisfies` verifies conformance to the catalog contract while keeping the
@@ -46,17 +69,23 @@ exports.yamlTransformer = {
 const RADIX_BY_FORMAT = { BIN: 2, OCT: 8, HEX: 16 };
 /**
  * Copy non-decimal integer presentation (`0x`/`0o`/`0b` literals) from the
- * parsed document onto the inferred schema as leaf/leafList `radix` display
- * hints — the plain-data inference cannot see them, because `toJS()` drops the
- * scalar format. The revert needs nothing: scalars are mutated in place, so an
- * edited value re-emits in its literal's own base. Across group-list items the
- * first non-decimal occurrence wins — one shared item schema cannot vary the
- * display per item. Schema-driven mode is untouched (JSON Schema has no radix
- * vocabulary).
+ * parsed document onto the schema as leaf/leafList `radix` display hints —
+ * neither plain-data inference (`toJS()` drops the scalar format) nor a JSON
+ * Schema (no radix vocabulary) can know the base a value was written in; the
+ * document is the only authority. Runs in every mode and fills gaps only, so
+ * a `radix` already on a leaf wins. The revert needs nothing: scalars are
+ * mutated in place, so an edited value re-emits in its literal's own base.
+ * Across group-list items the first non-decimal occurrence wins — one shared
+ * item schema cannot vary the display per item. Keyed containers — groups,
+ * choices, maps — resolve their children through {@link childrenOf}, so case
+ * fields and map entries annotate too.
  */
 function annotateRadix(node, schema) {
     switch (schema.kind) {
         case 'leaf': {
+            // Only number/string leaves render radix.
+            if (schema.type !== 'number' && schema.type !== 'string')
+                return;
             const radix = scalarRadix(node);
             if (radix && !schema.radix)
                 schema.radix = radix;
@@ -70,25 +99,27 @@ function annotateRadix(node, schema) {
                 schema.radix = radixes[0];
             return;
         }
-        case 'nodeGroup': {
+        case 'nodeGroupList': {
+            if (!(0, yaml_1.isSeq)(node))
+                return;
+            for (const item of node.items)
+                annotateRadix(item, schema.type);
+            return;
+        }
+        default: {
+            // nodeGroup / choice / map — keyed containers over a document mapping.
             if (!(0, yaml_1.isMap)(node))
                 return;
+            const keys = (0, schema_keys_1.childrenOf)(schema);
+            if (!keys)
+                return;
             for (const pair of node.items) {
-                const child = schema.children[pairKey(pair.key)];
+                const child = keys.get(pairKey(pair.key));
                 if (child)
                     annotateRadix(pair.value, child);
             }
             return;
         }
-        case 'nodeGroupList': {
-            if (!(0, yaml_1.isSeq)(node))
-                return;
-            for (const item of node.items)
-                annotateRadix(item, schema.type);
-            return;
-        }
-        default:
-            return; // choice/map never come out of plain-data inference
     }
 }
 /** The display radix of a non-decimal integer scalar node, else undefined. */
@@ -115,7 +146,8 @@ function normalizeBigInts(value) {
     if (Array.isArray(value))
         return value.map(normalizeBigInts);
     if (value && typeof value === 'object') {
-        const out = {};
+        // Null prototype: a `__proto__` document key must stay a data key.
+        const out = Object.create(null);
         for (const key of Object.keys(value))
             out[key] = normalizeBigInts(value[key]);
         return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",