ng-form-foundry-transformers 0.2.1

package/dist/core/registry.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransformerRegistry = void 0;
+/**
+ * A lookup of {@link Transformer}s by their `id`. Lets a consumer pick a format
+ * at runtime (`registry.get('yaml')`) instead of importing each transformer
+ * directly. Direct imports remain available and tree-shakeable for consumers
+ * that only need one format.
+ */
+class TransformerRegistry {
+    constructor() {
+        this.byId = new Map();
+    }
+    /** Register a transformer under its `id`. Throws if the `id` is already taken. */
+    register(transformer) {
+        if (this.byId.has(transformer.id)) {
+            throw new Error(`transformer '${transformer.id}' is already registered`);
+        }
+        this.byId.set(transformer.id, transformer);
+        return this;
+    }
+    /** Get a transformer by `id`, or `undefined` if none is registered. */
+    get(id) {
+        return this.byId.get(id);
+    }
+    /** Get a transformer by `id`, throwing a listing of known ids if absent. */
+    require(id) {
+        const t = this.byId.get(id);
+        if (!t) {
+            const known = [...this.byId.keys()].join(', ') || '(none)';
+            throw new Error(`no transformer registered for '${id}'. Registered: ${known}`);
+        }
+        return t;
+    }
+    /** The ids of all registered transformers. */
+    ids() {
+        return [...this.byId.keys()];
+    }
+}
+exports.TransformerRegistry = TransformerRegistry;

package/dist/core/schema.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The ng-form-foundry schema DTO — the JSON contract the Angular app renders.
+ *
+ * These are a framework-free structural mirror of ng-form-foundry's `NodeGroup`
+ * model: the same JSON shape, without the `@angular/forms` imports that the
+ * frontend package couples to its type-level `FormControl` inference. The
+ * adapter only produces schema *data*, so it needs the plain shapes; the
+ * frontend re-derives its typed `FormGroup` from the same JSON via
+ * `buildFormFromSchema`.
+ */
+export type LeafType = 'string' | 'number' | 'boolean' | 'enum';
+export interface Leaf {
+    kind: 'leaf';
+    name: string;
+    type: LeafType;
+    required?: true;
+    label?: string;
+    default?: string | number | boolean;
+    /** Present when `type` is `'enum'`. */
+    enum?: (string | number)[];
+}
+export interface LeafList {
+    kind: 'leafList';
+    name: string;
+    type: LeafType;
+    label?: string;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface NodeGroup {
+    kind: 'nodeGroup';
+    name: string;
+    label?: string;
+    root?: boolean;
+    /**
+     * When true, the group is optional and rendered with an on/off toggle: absent
+     * unless the user enables it. Maps a YANG presence container — present-but-empty
+     * serializes as `{}`, absent is omitted.
+     */
+    presence?: boolean;
+    children: Record<string, NodeType>;
+}
+export interface NodeGroupList {
+    kind: 'nodeGroupList';
+    name: string;
+    label?: string;
+    type: NodeGroup;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * 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.
+ */
+export interface Choice {
+    kind: 'choice';
+    name: string;
+    label?: string;
+    cases: Record<string, Record<string, NodeType>>;
+    default?: string;
+    mandatory?: boolean;
+}
+export type NodeType = Leaf | LeafList | NodeGroup | NodeGroupList | Choice;
+/** 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. */
+export type FormValue = Record<string, unknown>;

package/dist/core/schema.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * The ng-form-foundry schema DTO — the JSON contract the Angular app renders.
+ *
+ * These are a framework-free structural mirror of ng-form-foundry's `NodeGroup`
+ * model: the same JSON shape, without the `@angular/forms` imports that the
+ * frontend package couples to its type-level `FormControl` inference. The
+ * adapter only produces schema *data*, so it needs the plain shapes; the
+ * frontend re-derives its typed `FormGroup` from the same JSON via
+ * `buildFormFromSchema`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CASE_KEY = void 0;
+/** The form-value key that records which case of a {@link Choice} is active. */
+exports.CASE_KEY = '__case';

package/dist/core/transformer.d.ts

@@ -0,0 +1,48 @@
+import type { NodeGroup, FormValue } from './schema';
+/**
+ * A transformer's revert context: whatever a transformer needs to turn an edited
+ * {@link FormValue} back into its source format. Opaque to the catalog — each
+ * transformer defines and consumes its own concrete shape (the YANG transformer
+ * keeps the effective model, the YAML transformer keeps the parsed document and
+ * inferred type map). Kept alongside the schema, not sent to the form UI.
+ */
+export type BindingMap = unknown;
+/** The output of {@link Transformer.toSchema}: the form schema plus its revert context. */
+export interface TransformResult<TBinding = BindingMap> {
+    /** The ng-form-foundry schema to build a form from. */
+    schema: NodeGroup;
+    /** Revert context, passed back to {@link Transformer.toSource}. */
+    binding: TBinding;
+    /** Initial form value extracted from the source, if the source carried data. */
+    initialValue?: FormValue;
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Maps one source format to and from the ng-form-foundry schema. YANG, JSON
+ * Schema, and plain YAML/JSON config each implement this so a single catalog can
+ * turn any of them into an editable form and write the edited value back.
+ *
+ * `toSchema`/`toSource` may be sync or async — YANG compiles through an external
+ * engine (async), while YAML/JSON parse in-process (sync). Register instances in
+ * the {@link import('./registry').TransformerRegistry} to look them up by `id`.
+ *
+ * For **config formats** (YAML, JSON) the thing you load and the thing you save
+ * are the same document type, so `TData` defaults to `TSource`. For **schema
+ * formats** they differ: YANG's `toSchema` consumes a model source, but its
+ * `toSource` reverts to RFC 7951 instance *data* — a different type — so YANG
+ * sets `TData` explicitly.
+ *
+ * @typeParam TSource  what `toSchema` consumes (YAML text, a YANG source set…)
+ * @typeParam TData    what `toSource` produces (defaults to `TSource`)
+ * @typeParam TBinding the revert context shape this transformer round-trips
+ * @typeParam TOptions per-call options (e.g. an optional JSON Schema for YAML)
+ */
+export interface Transformer<TSource = unknown, TData = TSource, TBinding = BindingMap, TOptions = void> {
+    /** Stable catalog key, e.g. `'yang'`, `'yaml'`, `'json-schema'`. */
+    readonly id: string;
+    /** Turn a source document into a form schema (+ revert context and any initial value). */
+    toSchema(source: TSource, options?: TOptions): MaybePromise<TransformResult<TBinding>>;
+    /** Turn an edited form value back into the source data, using the binding from `toSchema`. */
+    toSource(value: FormValue, binding: TBinding): MaybePromise<TData>;
+}
+export {};

package/dist/core/transformer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ng-form-foundry-transformers — a catalog of source-format transformers that
+ * turn a model or config into an ng-form-foundry schema and revert the edited
+ * form value back to the source format.
+ *
+ * The {@link Transformer} contract is the common seam; each format lives under
+ * its own entry point and can be imported on its own (tree-shakeable):
+ *
+ *   - `yang` — YANG model → form → RFC 7951 data ({@link createYangTransformer},
+ *              {@link YangFormAdapter}).
+ *   - `yaml` — YAML config → form → YAML ({@link yamlTransformer}); JSON-Schema
+ *              driven or inferred from the data, comment-preserving on revert.
+ *   - `json` — JSON config → form → JSON ({@link jsonTransformer}); same builders
+ *              as `yaml`, indent preserved.
+ *
+ * Look transformers up at runtime through {@link TransformerRegistry}, or import
+ * the one you need directly.
+ */
+export * from './core';
+export * from './transformers/yang';
+export * from './transformers/yaml';
+export * from './transformers/json';

package/dist/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * ng-form-foundry-transformers — a catalog of source-format transformers that
+ * turn a model or config into an ng-form-foundry schema and revert the edited
+ * form value back to the source format.
+ *
+ * The {@link Transformer} contract is the common seam; each format lives under
+ * its own entry point and can be imported on its own (tree-shakeable):
+ *
+ *   - `yang` — YANG model → form → RFC 7951 data ({@link createYangTransformer},
+ *              {@link YangFormAdapter}).
+ *   - `yaml` — YAML config → form → YAML ({@link yamlTransformer}); JSON-Schema
+ *              driven or inferred from the data, comment-preserving on revert.
+ *   - `json` — JSON config → form → JSON ({@link jsonTransformer}); same builders
+ *              as `yaml`, indent preserved.
+ *
+ * Look transformers up at runtime through {@link TransformerRegistry}, or import
+ * the one you need directly.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Core: the Transformer contract, the registry, shared schema types and builders.
+__exportStar(require("./core"), exports);
+// Transformers.
+__exportStar(require("./transformers/yang"), exports);
+__exportStar(require("./transformers/yaml"), exports);
+__exportStar(require("./transformers/json"), exports);

package/dist/transformers/json/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JSON transformer — turn a JSON config document into an ng-form-foundry schema
+ * and write the edited value back to JSON. Drive the form from a JSON Schema when
+ * one is supplied, otherwise infer it from the data. Reuses the format-agnostic
+ * schema builders in `core`.
+ */
+export { jsonTransformer } from './json-transformer';
+export type { JsonOptions, JsonFormat } from './json-transformer';

package/dist/transformers/json/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * JSON transformer — turn a JSON config document into an ng-form-foundry schema
+ * and write the edited value back to JSON. Drive the form from a JSON Schema when
+ * one is supplied, otherwise infer it from the data. Reuses the format-agnostic
+ * schema builders in `core`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonTransformer = void 0;
+var json_transformer_1 = require("./json-transformer");
+Object.defineProperty(exports, "jsonTransformer", { enumerable: true, get: function () { return json_transformer_1.jsonTransformer; } });

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

@@ -0,0 +1,38 @@
+import type { FormValue } from '../../core/schema';
+import type { TransformResult } from '../../core/transformer';
+import { type JsonSchema } from '../../core/json-schema';
+/** Options for {@link jsonTransformer}'s `toSchema`. */
+export interface JsonOptions {
+    /**
+     * A JSON Schema describing the config. When given, the form is built from it;
+     * when omitted, the form is inferred from the JSON data itself.
+     */
+    schema?: JsonSchema;
+    /** Name for the root node group. Defaults to `__root__`. */
+    rootName?: string;
+}
+/** How the source was formatted, so `toSource` re-emits it the same way. */
+export interface JsonFormat {
+    /** Indent width in spaces (detected from the source; defaults to 2). */
+    indent: number;
+    /** Whether the source ended with a trailing newline. */
+    trailingNewline: boolean;
+}
+/**
+ * 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
+ * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
+ * serialization (`JSON.stringify`) are JSON-specific.
+ *
+ * Standard JSON has no comments, so revert re-serializes the edited value,
+ * preserving the source's indent width and trailing newline. Key order follows
+ * the form value (which follows the schema, derived from the original), so it is
+ * 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.
+ */
+export declare const jsonTransformer: {
+    id: string;
+    toSchema(source: string, options?: JsonOptions): TransformResult<JsonFormat>;
+    toSource(value: FormValue, binding: JsonFormat): string;
+};

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonTransformer = void 0;
+const infer_1 = require("../../core/infer");
+const json_schema_1 = require("../../core/json-schema");
+/**
+ * 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
+ * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
+ * serialization (`JSON.stringify`) are JSON-specific.
+ *
+ * Standard JSON has no comments, so revert re-serializes the edited value,
+ * preserving the source's indent width and trailing newline. Key order follows
+ * the form value (which follows the schema, derived from the original), so it is
+ * 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.
+ */
+exports.jsonTransformer = {
+    id: 'json',
+    toSchema(source, options) {
+        const data = (JSON.parse(source) ?? {});
+        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'),
+        };
+        return { schema, binding, initialValue: data };
+    },
+    toSource(value, binding) {
+        const text = JSON.stringify(value, null, binding.indent);
+        return binding.trailingNewline ? text + '\n' : text;
+    },
+};
+/** Indent width (in spaces) of the first indented line, or 2 if none/tabs. */
+function detectIndent(source) {
+    const match = source.match(/\n( +)\S/);
+    return match && match[1] ? match[1].length : 2;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * YAML transformer — turn a YAML config document into an ng-form-foundry schema
+ * and write the edited value back to YAML with comments preserved. Drive the form
+ * from a JSON Schema when one is supplied, otherwise infer it from the data.
+ *
+ * The schema builders it uses (`inferNodeGroup`, `jsonSchemaToNodeGroup`) live in
+ * `core` — they are format-agnostic and shared with the JSON transformer.
+ */
+export { yamlTransformer } from './yaml-transformer';
+export type { YamlOptions } from './yaml-transformer';
+export { applyValueToDocument } from './revert';

package/dist/transformers/yaml/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * YAML transformer — turn a YAML config document into an ng-form-foundry schema
+ * and write the edited value back to YAML with comments preserved. Drive the form
+ * from a JSON Schema when one is supplied, otherwise infer it from the data.
+ *
+ * The schema builders it uses (`inferNodeGroup`, `jsonSchemaToNodeGroup`) live in
+ * `core` — they are format-agnostic and shared with the JSON transformer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyValueToDocument = exports.yamlTransformer = void 0;
+var yaml_transformer_1 = require("./yaml-transformer");
+Object.defineProperty(exports, "yamlTransformer", { enumerable: true, get: function () { return yaml_transformer_1.yamlTransformer; } });
+var revert_1 = require("./revert");
+Object.defineProperty(exports, "applyValueToDocument", { enumerable: true, get: function () { return revert_1.applyValueToDocument; } });

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

@@ -0,0 +1,13 @@
+import { type Document } from 'yaml';
+/**
+ * Apply an edited form value onto a parsed YAML {@link Document} in place,
+ * preserving comments and formatting on every node that survives the edit.
+ *
+ * Existing scalars are mutated (`node.value = …`), which keeps their inline and
+ * leading comments; only genuinely new keys/items create fresh (comment-less)
+ * nodes, and keys/items dropped from the value are deleted along with their
+ * 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.
+ */
+export declare function applyValueToDocument(doc: Document, value: unknown): void;

package/dist/transformers/yaml/revert.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyValueToDocument = applyValueToDocument;
+const yaml_1 = require("yaml");
+/**
+ * Apply an edited form value onto a parsed YAML {@link Document} in place,
+ * preserving comments and formatting on every node that survives the edit.
+ *
+ * Existing scalars are mutated (`node.value = …`), which keeps their inline and
+ * leading comments; only genuinely new keys/items create fresh (comment-less)
+ * nodes, and keys/items dropped from the value are deleted along with their
+ * 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.
+ */
+function applyValueToDocument(doc, value) {
+    if (doc.contents == null) {
+        doc.contents = doc.createNode(value);
+        return;
+    }
+    applyAt(doc, [], value);
+}
+function applyAt(doc, path, value) {
+    const node = nodeAt(doc, path);
+    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;
+    }
+    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;
+    }
+    // scalar (string / number / boolean / null)
+    if ((0, yaml_1.isScalar)(node))
+        node.value = value;
+    else
+        replaceAt(doc, path, 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);
+    }
+    else {
+        doc.setIn(path, doc.createNode(value));
+    }
+}
+function nodeAt(doc, path) {
+    return path.length === 0 ? doc.contents : doc.getIn(path, true);
+}
+/** 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)));
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

@@ -0,0 +1,32 @@
+import { type Document } from 'yaml';
+import type { FormValue } from '../../core/schema';
+import type { TransformResult } from '../../core/transformer';
+import { type JsonSchema } from '../../core/json-schema';
+/** Options for {@link yamlTransformer}'s `toSchema`. */
+export interface YamlOptions {
+    /**
+     * A JSON Schema describing the config. When given, the form is built from it
+     * (types, required, enums, nested shape); when omitted, the form is inferred
+     * from the YAML data itself (structure + value types).
+     */
+    schema?: JsonSchema;
+    /** Name for the root node group. Defaults to `__root__`. */
+    rootName?: string;
+}
+/**
+ * A YAML {@link Transformer}: turn a YAML config document into a form and write
+ * the edited value back to YAML. Built for **editing config files** — the 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.
+ *
+ * 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;
+};

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yamlTransformer = void 0;
+const yaml_1 = require("yaml");
+const infer_1 = require("../../core/infer");
+const json_schema_1 = require("../../core/json-schema");
+const revert_1 = require("./revert");
+/**
+ * A YAML {@link Transformer}: turn a YAML config document into a form and write
+ * the edited value back to YAML. Built for **editing config files** — the 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.
+ *
+ * With a JSON Schema in {@link YamlOptions}, the form is schema-driven; without
+ * one it is inferred from the data.
+ */
+exports.yamlTransformer = {
+    id: 'yaml',
+    toSchema(source, options) {
+        const doc = (0, yaml_1.parseDocument)(source);
+        const data = (doc.toJS() ?? {});
+        const schema = options?.schema
+            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
+            : (0, infer_1.inferNodeGroup)(data, options?.rootName);
+        return { schema, binding: doc, initialValue: data };
+    },
+    toSource(value, binding) {
+        const doc = binding.clone();
+        (0, revert_1.applyValueToDocument)(doc, value);
+        return String(doc);
+    },
+    // `satisfies` verifies conformance to the catalog contract while keeping the
+    // concrete sync return types, so direct callers need no `await`.
+};

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

@@ -0,0 +1,40 @@
+import { CompileRequest, YangEngine } from './engine';
+import { ArtifactCache } from './cache';
+import { CompiledModel } from './model';
+import { FormValue, NodeGroup } from '../../core/schema';
+export interface CompileOptions extends CompileRequest {
+    /** Cache key for the compiled model — typically a hash of the yang-library. */
+    modelId: string;
+}
+/** Thrown by {@link YangFormAdapter.toYangData} when the engine rejects the reverted data. */
+export declare class YangValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * The framework-agnostic core.
+ *
+ * Resolves a YANG model into a compiled `{ schema, binding }` (caching by
+ * `modelId`), serves the frontend `NodeGroup` schema, and round-trips instance
+ * data through the plain form value. The `binding` (resolved YANG model) never
+ * leaves the adapter; only the `schema` is meant for the client.
+ *
+ * Construct it directly (`new YangFormAdapter(engine, cache)`) from any Node
+ * runtime — Express, a worker, a CLI — or wrap it in a framework provider. It
+ * imports nothing framework-specific; all environment access goes through the
+ * injected {@link YangEngine} and {@link ArtifactCache}.
+ */
+export declare class YangFormAdapter {
+    private readonly engine;
+    private readonly cache;
+    constructor(engine: YangEngine, cache?: ArtifactCache);
+    /** Resolve and map a model, or return the cached result for `modelId`. */
+    compile(opts: CompileOptions): Promise<CompiledModel>;
+    /** The `NodeGroup` schema DTO to hand the Angular app. Excludes the binding. */
+    getFormSchema(modelId: string): Promise<NodeGroup>;
+    /** RFC 7951 instance data (e.g. a device GET) → a plain form value to edit. */
+    toFormValue(rfc7951: unknown, modelId: string): Promise<FormValue>;
+    /** An edited form value → RFC 7951 data, validated by the engine, ready for write-back. */
+    toYangData(value: FormValue, modelId: string): Promise<Record<string, unknown>>;
+    private require;
+}

package/dist/transformers/yang/adapter.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YangFormAdapter = exports.YangValidationError = void 0;
+const cache_1 = require("./cache");
+const mapper_1 = require("./mapper");
+const revert_1 = require("./revert");
+/** Thrown by {@link YangFormAdapter.toYangData} when the engine rejects the reverted data. */
+class YangValidationError extends Error {
+    constructor(errors) {
+        super(`RFC 7951 validation failed:\n  ${errors.join('\n  ')}`);
+        this.errors = errors;
+        this.name = 'YangValidationError';
+    }
+}
+exports.YangValidationError = YangValidationError;
+/**
+ * The framework-agnostic core.
+ *
+ * Resolves a YANG model into a compiled `{ schema, binding }` (caching by
+ * `modelId`), serves the frontend `NodeGroup` schema, and round-trips instance
+ * data through the plain form value. The `binding` (resolved YANG model) never
+ * leaves the adapter; only the `schema` is meant for the client.
+ *
+ * Construct it directly (`new YangFormAdapter(engine, cache)`) from any Node
+ * runtime — Express, a worker, a CLI — or wrap it in a framework provider. It
+ * imports nothing framework-specific; all environment access goes through the
+ * injected {@link YangEngine} and {@link ArtifactCache}.
+ */
+class YangFormAdapter {
+    constructor(engine, cache = new cache_1.InMemoryCache()) {
+        this.engine = engine;
+        this.cache = cache;
+    }
+    /** Resolve and map a model, or return the cached result for `modelId`. */
+    async compile(opts) {
+        const cached = await this.cache.get(opts.modelId);
+        if (cached)
+            return cached;
+        const binding = await this.engine.resolve(opts);
+        const model = { schema: (0, mapper_1.mapToSchema)(binding), binding };
+        await this.cache.set(opts.modelId, model);
+        return model;
+    }
+    /** The `NodeGroup` schema DTO to hand the Angular app. Excludes the binding. */
+    async getFormSchema(modelId) {
+        return (await this.require(modelId)).schema;
+    }
+    /** RFC 7951 instance data (e.g. a device GET) → a plain form value to edit. */
+    async toFormValue(rfc7951, modelId) {
+        return (0, revert_1.toFormValue)(rfc7951, (await this.require(modelId)).binding);
+    }
+    /** An edited form value → RFC 7951 data, validated by the engine, ready for write-back. */
+    async toYangData(value, modelId) {
+        const model = await this.require(modelId);
+        const data = (0, revert_1.toYangData)(value, model.binding);
+        const result = await this.engine.validate(data, model.binding);
+        if (!result.valid)
+            throw new YangValidationError(result.errors);
+        return data;
+    }
+    async require(modelId) {
+        const model = await this.cache.get(modelId);
+        if (!model)
+            throw new Error(`model '${modelId}' is not compiled — call compile() first`);
+        return model;
+    }
+}
+exports.YangFormAdapter = YangFormAdapter;