@json-to-office/core-docx 0.16.0 → 0.17.1

package/dist/core/generator.d.ts

@@ -12,8 +12,19 @@ import type { GenerationWarning } from '@json-to-office/shared';
 export interface JsonGenerationOptions {
     outputPath?: string;
     validation?: {
-        strict?: boolean;
+        /**
+         * Validate the document against the schema before building, throwing on
+         * errors. Defaults to `true` — invalid props are surfaced rather than
+         * silently dropped into a corrupt/incomplete document.
+         */
+        enabled?: boolean;
+        /**
+         * When true, unknown/extra properties are stripped instead of rejected by
+         * strict (additionalProperties:false) schemas. Escape hatch for migration.
+         */
         allowUnknownFields?: boolean;
+        /** @deprecated No longer consulted; retained for back-compat. */
+        strict?: boolean;
     };
     customThemes?: {
         [key: string]: ThemeConfig;

package/dist/core/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/core/generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/core/generator.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7287,9 +7287,32 @@ async function generateDocumentWithCustomThemes(documentIn, customThemes, servic
   return renderedDocument;
 }
 async function generateDocumentFromJson(jsonConfig, options) {
+  const validation = options?.validation;
+  if (validation?.enabled !== false) {
+    const result = validateJsonComponent(jsonConfig, {
+      allowUnknownFields: validation?.allowUnknownFields
+    });
+    if (!result.valid) {
+      throw new JsonValidationError(
+        "Document validation failed",
+        result.errors
+      );
+    }
+  }
   let componentToConvert;
   if (typeof jsonConfig === "string") {
-    const parsed = parseJsonComponent(jsonConfig);
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonConfig);
+    } catch (error) {
+      throw new JsonParsingError("Invalid JSON syntax", [
+        {
+          path: "",
+          message: error instanceof Error ? error.message : "Invalid JSON",
+          code: "JSON_PARSE_ERROR"
+        }
+      ]);
+    }
     if (!isReportComponent(parsed)) {
       throw new Error("Parsed JSON must be a docx component");
     }
@@ -7690,22 +7713,20 @@ import {
   ComponentValidationError as ComponentValidationError2,
   UnknownPreservedComponentError
 } from "@json-to-office/shared/plugin";
-function validateComponentProps(schema, props, componentName) {
+function validateComponentProps(schema, props, componentName, opts) {
   return validateCustomComponentProps(schema.propsSchema, props, {
-    clean: true,
-    applyDefaults: true,
+    clean: opts?.clean ?? true,
+    applyDefaults: opts?.applyDefaults ?? true,
     componentName
   });
 }
-function validateDocument(document, customComponents) {
+function validateDocument(document, customComponents, options) {
+  const knownCustomNames = new Set(customComponents.map((c) => c.name));
   const documentResult = validateDocumentUnified(document, {
-    clean: true,
-    applyDefaults: true
+    knownCustomNames,
+    allowUnknownFields: options?.allowUnknownFields
   });
-  if (!documentResult.valid) {
-    return { ...documentResult, success: false };
-  }
-  const errors = [];
+  const errors = [...documentResult.errors || []];
   function validateComponents(components, pathPrefix = "children") {
     components.forEach((componentData, index) => {
       const customComponent = customComponents.find(
@@ -7722,7 +7743,9 @@ function validateDocument(document, customComponents) {
       const validation = validateComponentProps(
         versionEntry,
         componentData.props,
-        customComponent.name
+        customComponent.name,
+        // Reject unknown custom props unless the caller allows them.
+        { clean: options?.allowUnknownFields === true }
       );
       if (!validation.valid && validation.errors) {
         const indexedErrors = validation.errors.map(
@@ -7933,7 +7956,7 @@ function createBuilderImpl(state) {
     }
     return getThemeWithFallback(themeName);
   }
-  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, depth = 0) {
+  async function processDocumentComponents(components, preserveSet, warningsCollector, resolvedTheme, validateEmitted, depth = 0) {
     if (depth > 20) {
       throw new Error(
         "Maximum component nesting depth exceeded (20). Check for circular component references."
@@ -7973,6 +7996,7 @@ function createBuilderImpl(state) {
               preserveSet,
               warningsCollector,
               resolvedTheme,
+              validateEmitted,
               depth + 1
             );
             nestedChildren = nested.standard;
@@ -7993,11 +8017,15 @@ function createBuilderImpl(state) {
             children: nestedChildren
           });
           const resultComponents = Array.isArray(result) ? result : [result];
+          if (validateEmitted) {
+            validateEmitted(resultComponents, versionLabel);
+          }
           const processedResult = await processDocumentComponents(
             resultComponents,
             preserveSet,
             warningsCollector,
             resolvedTheme,
+            validateEmitted,
             depth + 1
           );
           standardOut.push(...processedResult.standard);
@@ -8027,6 +8055,7 @@ function createBuilderImpl(state) {
             preserveSet,
             warningsCollector,
             resolvedTheme,
+            validateEmitted,
             depth + 1
           );
           standardOut.push({
@@ -8087,10 +8116,42 @@ function createBuilderImpl(state) {
     try {
       const preserveSet = resolvePreserveSet(options);
       const internalDocument = document;
-      validateDocument(
-        internalDocument,
-        state.components
-      );
+      const vOpts = {
+        ...state.validation,
+        ...options?.validation
+      };
+      if (vOpts.enabled !== false) {
+        const result = validateDocument(
+          internalDocument,
+          state.components,
+          { allowUnknownFields: vOpts.allowUnknownFields }
+        );
+        if (!result.valid) {
+          throw new ComponentValidationError2(
+            (result.errors ?? []).map((e) => ({
+              path: e.path ?? "",
+              message: e.message
+            })),
+            internalDocument
+          );
+        }
+      }
+      const validateEmitted = vOpts.enabled === false ? void 0 : (emitted, componentLabel) => {
+        const result = validateDocument(
+          { ...internalDocument, children: emitted },
+          state.components,
+          { allowUnknownFields: vOpts.allowUnknownFields }
+        );
+        if (!result.valid) {
+          throw new ComponentValidationError2(
+            (result.errors ?? []).map((e) => ({
+              path: e.path ?? "",
+              message: `custom component '${componentLabel}' emitted invalid output \u2014 ${e.message}`
+            })),
+            emitted
+          );
+        }
+      };
       const baseThemeName = internalDocument.props.theme || "minimal";
       const docTheme = resolveDocumentTheme(baseThemeName);
       const warnings = [];
@@ -8113,7 +8174,8 @@ function createBuilderImpl(state) {
         mode.doc.children || [],
         preserveSet,
         warnings,
-        modedTheme
+        modedTheme,
+        validateEmitted
       );
       const processedDocument = {
         ...mode.doc,
@@ -8184,21 +8246,21 @@ function createBuilderImpl(state) {
   function validate(document) {
     try {
       const internalDocument = document;
-      validateDocument(
+      const result = validateDocument(
         internalDocument,
         state.components
       );
-      return { valid: true };
-    } catch (error) {
-      if (error instanceof ComponentValidationError2) {
-        return {
-          valid: false,
-          errors: error.errors.map((e) => ({
-            path: e.path,
-            message: e.message
-          }))
-        };
+      if (result.valid) {
+        return { valid: true };
       }
+      return {
+        valid: false,
+        errors: (result.errors ?? []).map((e) => ({
+          path: e.path ?? "",
+          message: e.message
+        }))
+      };
+    } catch (error) {
       return {
         valid: false,
         errors: [
@@ -8248,7 +8310,8 @@ function createDocumentGenerator(options) {
     debug: options.debug ?? false,
     enableCache: options.enableCache ?? false,
     services: options.services,
-    fonts: options.fonts
+    fonts: options.fonts,
+    validation: options.validation
   };
   return createBuilderImpl(initialState);
 }