@makehq/forman-schema 1.19.0 → 2.0.0

package/README.md

@@ -2,6 +2,15 @@
 
 Conversion and validation utilities for Forman Schema.
 
+## v2.0.0 — validated values on every result
+
+`validateForman` and `validateFormanWithDomains` now always return `normalizedValues` and
+`appliedDefaults`. Nothing was removed or renamed and `valid`/`errors`/`warnings` are unaffected,
+but a caller that deep-compares the whole result, or forwards it into a fixed-shape response, will
+see two new keys — assert on the fields you care about, or drop the keys before forwarding.
+
+Also new: `fillDefaults: 'always'`. See [Filling defaults](#filling-defaults).
+
 ## v1.14.0 — advanced field tracking
 
 Non-breaking minor release. New surface for working with `advanced: true` Forman fields:
@@ -137,7 +146,16 @@ Validate Forman values against a Forman Schema. Two entry points are available:
 - `validateForman(values, schema, options?)` — validate without domains.
 - `validateFormanWithDomains(domains, options?)` — validate multiple domains at once.
 
-Both return `{ valid: boolean, errors: { path: string, message: string }[] }`.
+Both return `{ valid: boolean, errors: { path: string, message: string }[] }`, plus
+`normalizedValues` (the input values per domain, with any filled defaults applied — see
+[Filling defaults](#filling-defaults)) and `appliedDefaults` (what was filled, empty when
+nothing was). The two are always present, so the consuming pattern is the same whether or
+not default filling is enabled:
+
+```typescript
+const { valid, errors, normalizedValues } = await validateForman(values, schema);
+if (valid) persist(normalizedValues.default);
+```
 
 #### Basic validation
 
@@ -219,6 +237,43 @@ const result = await validateForman(values, schema, {
 });
 ```
 
+#### Filling defaults
+
+With `fillDefaults: 'requiredOnly'`, an omitted required field whose schema declares a usable
+default (`null` and `''` cannot satisfy a required check) validates as that default instead of
+failing as mandatory. With `fillDefaults: 'always'`, omitted optional fields with usable defaults
+are filled too — the same modes as the platform's BlueprintValidator `useDefaults` option. The
+filled value participates in the rest of the walk, so a filled boolean conditions its nested branch
+exactly as a provided one would, and defaults under an armed branch fill recursively — including
+fields injected by `rpc://`-resolved specs. Fills land in `normalizedValues` (the values with fills
+applied; the input is never mutated, though subtrees nothing was written into are shared with it)
+and are itemized in `appliedDefaults`, on the failure path too, so remaining errors can be repaired
+on top of the filled values. Values you provide are never overwritten, **except `''`, which counts as
+an omission and fills** — matching blueprint validation and the builder UI. Under `'always'` that
+means an optional field you deliberately cleared comes back with its default; pass `'requiredOnly'`
+if you need a cleared optional field left alone. An explicit `null` is a provided value: it never
+fills and still fails as mandatory. Inactive nested branches are never filled.
+
+```typescript
+const schema = [
+    {
+        name: 'fallbackEnabled',
+        type: 'boolean',
+        required: true,
+        default: false,
+        nested: [{ name: 'fallbackConnectionId', type: 'text', required: true }],
+    },
+];
+
+const result = await validateForman({}, schema, { fillDefaults: 'requiredOnly' });
+// {
+//   valid: true,
+//   errors: [],
+//   normalizedValues: { default: { fallbackEnabled: false } },
+//   appliedDefaults: [{ domain: 'default', path: 'fallbackEnabled', value: false }]
+// }
+```
+
 #### Multi-domain validation
 
 Use `validateFormanWithDomains` to validate cross-domain schemas (e.g., `default` and `additional`).

package/dist/index.cjs

@@ -115,6 +115,27 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => valueKey in option && matches(option));
   return found;
 }
+function setIn(container, path, value) {
+  const [head, ...rest] = path;
+  if (head === void 0) return value;
+  if (typeof head === "number") {
+    const items = Array.isArray(container) ? container.slice() : [];
+    items[head] = setIn(items[head], rest, value);
+    return items;
+  }
+  const record = isObject(container) ? { ...container } : {};
+  record[head] = setIn(record[head], rest, value);
+  return record;
+}
+function setValueAtPath(values, path, value) {
+  const [head] = path;
+  if (typeof head !== "string") {
+    throw new Error(`Cannot write a value at path '${path.join(".")}': the first segment must be a field name.`);
+  }
+  const record = { ...values };
+  record[head] = setIn(record[head], path.slice(1), value);
+  return record;
+}
 function pathToString(path) {
   let result = "";
   for (const key of path) {
@@ -1292,6 +1313,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         seenFields: /* @__PURE__ */ new Set(),
         fieldStates: [],
         schemaFields: [],
+        appliedDefaults: [],
         allowDynamicValues: domains[domain].allowDynamicValues ?? options?.allowDynamicValues ?? false,
         validateFields: (fields, context) => {
           return validateFormanValue(
@@ -1328,6 +1350,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         path: [],
         tail: [],
         strict: options?.strict === true,
+        fillDefaults: options?.fillDefaults,
         domainAliases: options?.domainAliases ?? {},
         validateNestedFields: () => {
           throw new Error("Cannot validate nested fields without parent field.");
@@ -1397,7 +1420,23 @@ async function validateFormanWithDomainsInternal(domains, options) {
     // built before the verdict, so a rejection can name the fields it rejected instead of
     // leaving the caller to guess at a sub-form it never saw. `schemas` stays success-only:
     // callers read its presence as a success signal.
-    resolvedSchemas: options?.schemas ? Object.fromEntries(Object.keys(domains).map((domain) => [domain, roots[domain].schemaFields])) : void 0
+    resolvedSchemas: options?.schemas ? Object.fromEntries(Object.keys(domains).map((domain) => [domain, roots[domain].schemaFields])) : void 0,
+    normalizedValues: Object.fromEntries(
+      Object.keys(domains).map((domain) => [
+        domain,
+        (roots[domain]?.appliedDefaults ?? []).reduce(
+          (values, { path, value }) => setValueAtPath(values, path, value),
+          domains[domain]?.values ?? {}
+        )
+      ])
+    ),
+    appliedDefaults: Object.keys(domains).flatMap(
+      (domain) => roots[domain]?.appliedDefaults.map(({ path, value }) => ({
+        domain,
+        path: path.join("."),
+        value
+      })) ?? []
+    )
   };
 }
 async function validateFormanValue(value, field, context) {
@@ -1429,6 +1468,14 @@ async function validateFormanValue(value, field, context) {
     };
   }
   const normalizedField = normalizeFormanFieldType(field);
+  if (context.fillDefaults != null && !context.suppressRequired && (value === void 0 || value === "") && (context.fillDefaults === "always" || normalizedField.required)) {
+    const fillable = normalizedField.default;
+    if (fillable != null && fillable !== "") {
+      const filled = isObject(fillable) || Array.isArray(fillable) ? structuredClone(fillable) : fillable;
+      value = filled;
+      context.roots[context.domain].appliedDefaults.push({ path: [...context.path], value: filled });
+    }
+  }
   if (normalizedField.required && !context.suppressRequired && (value == null || value === "")) {
     return {
       valid: false,

package/dist/index.d.cts

@@ -225,7 +225,28 @@ type FormanValidationResult = {
      * which fields it rejected.
      */
     resolvedSchemas?: Record<string, FormanSchemaField[]>;
+    /**
+     * The input values with filled defaults applied, per domain, so a caller can persist or repair
+     * the filled configuration alongside any remaining errors. The input `values` are never
+     * mutated, but subtrees no default was written into are shared with the input — with no fills
+     * the domain's entry IS the caller's own object.
+     */
+    normalizedValues?: Record<string, Record<string, unknown>>;
+    /** The defaults that were filled (`options.fillDefaults`), in walk order within each domain. */
+    appliedDefaults?: {
+        domain: string;
+        path: string;
+        /** The default that was filled in. Loosely typed on purpose: `default` is declared as
+         *  `FormanSchemaValue`, but schemas are JSON at source and may carry object or array
+         *  defaults at runtime, which are filled as (cloned) values too. */
+        value: unknown;
+    }[];
 };
+/**
+ * The type returned by `validateForman` and `validateFormanWithDomains`. The fields stay optional
+ * on the base type because intermediate results assembled during the walk do not carry them.
+ */
+type FormanNormalizedValidationResult = FormanValidationResult & Required<Pick<FormanValidationResult, 'normalizedValues' | 'appliedDefaults'>>;
 type FormanSchemaFieldState = {
     mode?: 'chose' | 'edit';
     label?: string;
@@ -304,6 +325,20 @@ type FormanValidationOptions = {
      *  returns (or resolves to) a result fragment that is spliced into the overall validation
      *  result. When omitted, `json` fields with a `schema` pass without schema validation. */
     validateJson?(schema: JSONSchema7, value: unknown): FormanExternalValidationResult | Promise<FormanExternalValidationResult>;
+    /** Fill declared defaults for fields the caller omitted, mirroring BlueprintValidator's
+     *  `useDefaults` modes. `'requiredOnly'` fills only required fields (instead of failing them
+     *  as mandatory); `'always'` also fills omitted optional fields. A field is fillable when its
+     *  value is `undefined` or `''` and its schema declares a default that is not `null` or `''`
+     *  (a default that could not satisfy a required check) — the same fillable predicate as
+     *  BlueprintValidator and the builder UI. The filled value flows through the rest of the
+     *  walk, so a filled boolean conditions its nested branch exactly as a provided one would
+     *  (`false` leaves the branch inactive), and defaults under an armed branch fill
+     *  recursively, in the same single pass. Fills are reported on `normalizedValues` and
+     *  `appliedDefaults`. Values the caller provided are never overwritten, except `''`, which
+     *  counts as an omission and fills — so under `'always'` a deliberately cleared optional
+     *  field comes back with its default. An explicit `null` is a provided value: it never fills
+     *  and still fails as mandatory. Inactive branches are never filled. */
+    fillDefaults?: 'requiredOnly' | 'always';
     /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
     domainAliases?: Record<string, string>;
     /** Whether to allow dynamic values (IML expressions, unresolved RPC options).
@@ -400,7 +435,7 @@ declare function validateFormanWithDomains(domains: Record<string, {
     /** Whether the domain allows dynamic values (IML expressions, unresolved RPC select options).
      *  Defaults to false. When false, IML expressions cause errors and unresolved RPC options are treated as errors. */
     allowDynamicValues?: boolean;
-}>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
+}>, options?: FormanValidationOptions): Promise<FormanNormalizedValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
@@ -411,6 +446,6 @@ declare function validateFormanWithDomains(domains: Record<string, {
  *   and backtick-escaping for keys containing dots (e.g. `"a.b[0].c"`, `` "`dotted.key`.child" ``).
  * @returns The validation result
  */
-declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanNormalizedValidationResult>;
 
-export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaBooleanNested, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };
+export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanNormalizedValidationResult, type FormanSchemaBooleanNested, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };

package/dist/index.d.ts

@@ -225,7 +225,28 @@ type FormanValidationResult = {
      * which fields it rejected.
      */
     resolvedSchemas?: Record<string, FormanSchemaField[]>;
+    /**
+     * The input values with filled defaults applied, per domain, so a caller can persist or repair
+     * the filled configuration alongside any remaining errors. The input `values` are never
+     * mutated, but subtrees no default was written into are shared with the input — with no fills
+     * the domain's entry IS the caller's own object.
+     */
+    normalizedValues?: Record<string, Record<string, unknown>>;
+    /** The defaults that were filled (`options.fillDefaults`), in walk order within each domain. */
+    appliedDefaults?: {
+        domain: string;
+        path: string;
+        /** The default that was filled in. Loosely typed on purpose: `default` is declared as
+         *  `FormanSchemaValue`, but schemas are JSON at source and may carry object or array
+         *  defaults at runtime, which are filled as (cloned) values too. */
+        value: unknown;
+    }[];
 };
+/**
+ * The type returned by `validateForman` and `validateFormanWithDomains`. The fields stay optional
+ * on the base type because intermediate results assembled during the walk do not carry them.
+ */
+type FormanNormalizedValidationResult = FormanValidationResult & Required<Pick<FormanValidationResult, 'normalizedValues' | 'appliedDefaults'>>;
 type FormanSchemaFieldState = {
     mode?: 'chose' | 'edit';
     label?: string;
@@ -304,6 +325,20 @@ type FormanValidationOptions = {
      *  returns (or resolves to) a result fragment that is spliced into the overall validation
      *  result. When omitted, `json` fields with a `schema` pass without schema validation. */
     validateJson?(schema: JSONSchema7, value: unknown): FormanExternalValidationResult | Promise<FormanExternalValidationResult>;
+    /** Fill declared defaults for fields the caller omitted, mirroring BlueprintValidator's
+     *  `useDefaults` modes. `'requiredOnly'` fills only required fields (instead of failing them
+     *  as mandatory); `'always'` also fills omitted optional fields. A field is fillable when its
+     *  value is `undefined` or `''` and its schema declares a default that is not `null` or `''`
+     *  (a default that could not satisfy a required check) — the same fillable predicate as
+     *  BlueprintValidator and the builder UI. The filled value flows through the rest of the
+     *  walk, so a filled boolean conditions its nested branch exactly as a provided one would
+     *  (`false` leaves the branch inactive), and defaults under an armed branch fill
+     *  recursively, in the same single pass. Fills are reported on `normalizedValues` and
+     *  `appliedDefaults`. Values the caller provided are never overwritten, except `''`, which
+     *  counts as an omission and fills — so under `'always'` a deliberately cleared optional
+     *  field comes back with its default. An explicit `null` is a provided value: it never fills
+     *  and still fails as mandatory. Inactive branches are never filled. */
+    fillDefaults?: 'requiredOnly' | 'always';
     /** Maps domain names used in nested.domain to actual domain keys passed to validateFormanWithDomains */
     domainAliases?: Record<string, string>;
     /** Whether to allow dynamic values (IML expressions, unresolved RPC options).
@@ -400,7 +435,7 @@ declare function validateFormanWithDomains(domains: Record<string, {
     /** Whether the domain allows dynamic values (IML expressions, unresolved RPC select options).
      *  Defaults to false. When false, IML expressions cause errors and unresolved RPC options are treated as errors. */
     allowDynamicValues?: boolean;
-}>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
+}>, options?: FormanValidationOptions): Promise<FormanNormalizedValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
@@ -411,6 +446,6 @@ declare function validateFormanWithDomains(domains: Record<string, {
  *   and backtick-escaping for keys containing dots (e.g. `"a.b[0].c"`, `` "`dotted.key`.child" ``).
  * @returns The validation result
  */
-declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanNormalizedValidationResult>;
 
-export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanSchemaBooleanNested, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };
+export { type FormanExternalValidationResult, type FormanJsonSchemaOptions, type FormanJsonSchemaResult, type FormanNormalizedValidationResult, type FormanSchemaBooleanNested, type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, type FormanValidationOptions, type FormanValidationResult, SchemaConversionError, resolveFormanFieldType, toFormanSchema, toJSONSchema, toJSONSchemaAdvanced, validateForman, validateFormanWithDomains };

package/dist/index.js

@@ -83,6 +83,27 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => valueKey in option && matches(option));
   return found;
 }
+function setIn(container, path, value) {
+  const [head, ...rest] = path;
+  if (head === void 0) return value;
+  if (typeof head === "number") {
+    const items = Array.isArray(container) ? container.slice() : [];
+    items[head] = setIn(items[head], rest, value);
+    return items;
+  }
+  const record = isObject(container) ? { ...container } : {};
+  record[head] = setIn(record[head], rest, value);
+  return record;
+}
+function setValueAtPath(values, path, value) {
+  const [head] = path;
+  if (typeof head !== "string") {
+    throw new Error(`Cannot write a value at path '${path.join(".")}': the first segment must be a field name.`);
+  }
+  const record = { ...values };
+  record[head] = setIn(record[head], path.slice(1), value);
+  return record;
+}
 function pathToString(path) {
   let result = "";
   for (const key of path) {
@@ -1260,6 +1281,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         seenFields: /* @__PURE__ */ new Set(),
         fieldStates: [],
         schemaFields: [],
+        appliedDefaults: [],
         allowDynamicValues: domains[domain].allowDynamicValues ?? options?.allowDynamicValues ?? false,
         validateFields: (fields, context) => {
           return validateFormanValue(
@@ -1296,6 +1318,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
         path: [],
         tail: [],
         strict: options?.strict === true,
+        fillDefaults: options?.fillDefaults,
         domainAliases: options?.domainAliases ?? {},
         validateNestedFields: () => {
           throw new Error("Cannot validate nested fields without parent field.");
@@ -1365,7 +1388,23 @@ async function validateFormanWithDomainsInternal(domains, options) {
     // built before the verdict, so a rejection can name the fields it rejected instead of
     // leaving the caller to guess at a sub-form it never saw. `schemas` stays success-only:
     // callers read its presence as a success signal.
-    resolvedSchemas: options?.schemas ? Object.fromEntries(Object.keys(domains).map((domain) => [domain, roots[domain].schemaFields])) : void 0
+    resolvedSchemas: options?.schemas ? Object.fromEntries(Object.keys(domains).map((domain) => [domain, roots[domain].schemaFields])) : void 0,
+    normalizedValues: Object.fromEntries(
+      Object.keys(domains).map((domain) => [
+        domain,
+        (roots[domain]?.appliedDefaults ?? []).reduce(
+          (values, { path, value }) => setValueAtPath(values, path, value),
+          domains[domain]?.values ?? {}
+        )
+      ])
+    ),
+    appliedDefaults: Object.keys(domains).flatMap(
+      (domain) => roots[domain]?.appliedDefaults.map(({ path, value }) => ({
+        domain,
+        path: path.join("."),
+        value
+      })) ?? []
+    )
   };
 }
 async function validateFormanValue(value, field, context) {
@@ -1397,6 +1436,14 @@ async function validateFormanValue(value, field, context) {
     };
   }
   const normalizedField = normalizeFormanFieldType(field);
+  if (context.fillDefaults != null && !context.suppressRequired && (value === void 0 || value === "") && (context.fillDefaults === "always" || normalizedField.required)) {
+    const fillable = normalizedField.default;
+    if (fillable != null && fillable !== "") {
+      const filled = isObject(fillable) || Array.isArray(fillable) ? structuredClone(fillable) : fillable;
+      value = filled;
+      context.roots[context.domain].appliedDefaults.push({ path: [...context.path], value: filled });
+    }
+  }
   if (normalizedField.required && !context.suppressRequired && (value == null || value === "")) {
     return {
       valid: false,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/forman-schema",
-    "version": "1.19.0",
+    "version": "2.0.0",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",