@makehq/forman-schema 1.8.4 → 1.9.1

package/dist/index.cjs

@@ -98,6 +98,60 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => "value" in option && option.value === value);
   return found;
 }
+function pathToString(path) {
+  let result = "";
+  for (const key of path) {
+    if (typeof key === "number") {
+      result += `[${key}]`;
+    } else {
+      if (result.length > 0) {
+        result += ".";
+      }
+      if (key.includes("`")) {
+        throw new Error(`Invalid path key: backticks are not allowed in key "${key}"`);
+      }
+      result += key.includes(".") ? `\`${key}\`` : key;
+    }
+  }
+  return result;
+}
+function stringToPath(str) {
+  const path = [];
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ".") {
+      i++;
+      if (i >= str.length) break;
+    }
+    if (str[i] === "[") {
+      const end = str.indexOf("]", i);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing bracket in "${str}"`);
+      }
+      const num = Number(str.slice(i + 1, end));
+      if (!Number.isInteger(num) || num < 0) {
+        throw new Error(`Invalid path: non-numeric or negative index in "${str}"`);
+      }
+      path.push(num);
+      i = end + 1;
+    } else if (str[i] === "`") {
+      const end = str.indexOf("`", i + 1);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing backtick in "${str}"`);
+      }
+      path.push(str.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      let end = i;
+      while (end < str.length && str[end] !== "." && str[end] !== "[") {
+        end++;
+      }
+      path.push(str.slice(i, end));
+      i = end;
+    }
+  }
+  return path;
+}
 function buildRestoreStructure(items) {
   const result = {};
   for (const item of items) {
@@ -531,7 +585,8 @@ function validateFormanField(field) {
 }
 function appendQueryString(path, domain, tail) {
   if (path.startsWith("api://")) return path;
-  const queryString = tail.map((part) => `${encodeURIComponent(part)}={{${part}}}`).join("&");
+  const existingParams = new Set(new URL(path).searchParams.keys());
+  const queryString = tail.filter((part) => !existingParams.has(part)).map((part) => `${encodeURIComponent(part)}={{${part}}}`).join("&");
   if (!queryString) return path;
   const separator = path.includes("?") ? "&" : "?";
   return `${path}${separator}${queryString}`;
@@ -1079,6 +1134,25 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     );
     errors.push(...result.errors);
+    const restoreExtras = options?.states && domains[domain]?.restoreExtras;
+    if (restoreExtras) {
+      const fieldStateMap = new Map(
+        roots[domain].fieldStates.map(({ path, state }) => {
+          return [pathToString(path), state];
+        })
+      );
+      for (const [fieldPath, extra] of Object.entries(restoreExtras)) {
+        const state = fieldStateMap.get(fieldPath);
+        if (state) {
+          state.extra = extra;
+        } else {
+          roots[domain].fieldStates.push({
+            path: stringToPath(fieldPath),
+            state: { extra }
+          });
+        }
+      }
+    }
   }
   return {
     valid: errors.length === 0,
@@ -1506,11 +1580,14 @@ async function handleSelectType(value, field, context) {
       if (resolved == null || typeof resolved !== "object") {
         return {
           valid: false,
-          errors: [...errors, {
-            domain: context.domain,
-            path: context.path.join("."),
-            message: `Remote resource ${optionsOrGroups} returned no data.`
-          }]
+          errors: [
+            ...errors,
+            {
+              domain: context.domain,
+              path: context.path.join("."),
+              message: `Remote resource ${optionsOrGroups} returned no data.`
+            }
+          ]
         };
       }
       optionsOrGroups = Array.isArray(resolved) ? resolved : [resolved];
@@ -1876,8 +1953,8 @@ function toJSONSchema(field) {
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
 }
-function validateForman(values, schema, options) {
-  return validateFormanWithDomains({ default: { values, schema } }, options);
+function validateForman(values, schema, options, restoreExtras) {
+  return validateFormanWithDomains({ default: { values, schema, restoreExtras } }, options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -205,6 +205,7 @@ type FormanSchemaFieldState = {
     label?: string;
     path?: Array<string>;
     data?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
@@ -239,14 +240,19 @@ declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
 declare function validateFormanWithDomains(domains: Record<string, {
     values: Record<string, unknown>;
     schema: FormanSchemaField[];
+    /** Extra values injected into restore states, keyed by string path (dot notation, `[index]`, backtick-escaping). */
+    restoreExtras?: Record<string, Record<string, unknown>>;
 }>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
  * @param schema The schema to validate against
  * @param options The validation options
+ * @param restoreExtras Values to be injected into restore objects of particular fields.
+ *   Keyed by string path using dot notation for nested keys, `[index]` for array indices,
+ *   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): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
 export { type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, toFormanSchema, toJSONSchema, validateForman, validateFormanWithDomains };

package/dist/index.d.ts

@@ -205,6 +205,7 @@ type FormanSchemaFieldState = {
     label?: string;
     path?: Array<string>;
     data?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
     nested?: Record<string, FormanSchemaFieldState>;
     items?: Record<string, FormanSchemaFieldState>[];
 };
@@ -239,14 +240,19 @@ declare function toJSONSchema(field: FormanSchemaField): JSONSchema7;
 declare function validateFormanWithDomains(domains: Record<string, {
     values: Record<string, unknown>;
     schema: FormanSchemaField[];
+    /** Extra values injected into restore states, keyed by string path (dot notation, `[index]`, backtick-escaping). */
+    restoreExtras?: Record<string, Record<string, unknown>>;
 }>, options?: FormanValidationOptions): Promise<FormanValidationResult>;
 /**
  * Validates a simple Forman values against a schema
  * @param values The values to validate
  * @param schema The schema to validate against
  * @param options The validation options
+ * @param restoreExtras Values to be injected into restore objects of particular fields.
+ *   Keyed by string path using dot notation for nested keys, `[index]` for array indices,
+ *   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): Promise<FormanValidationResult>;
+declare function validateForman(values: Record<string, unknown>, schema: FormanSchemaField[], options?: FormanValidationOptions, restoreExtras?: Record<string, Record<string, unknown>>): Promise<FormanValidationResult>;
 
 export { type FormanSchemaDirectoryOption, type FormanSchemaExtendedNested, type FormanSchemaExtendedOptions, type FormanSchemaField, type FormanSchemaFieldType, type FormanSchemaNested, type FormanSchemaOption, type FormanSchemaOptionGroup, type FormanSchemaPathExtendedOptions, type FormanSchemaRPCButton, type FormanSchemaValue, toFormanSchema, toJSONSchema, validateForman, validateFormanWithDomains };

package/dist/index.js

@@ -69,6 +69,60 @@ function findValueInSelectOptions(field, value, optionsAndGroups) {
   const found = optionsAndGroups.find((option) => "value" in option && option.value === value);
   return found;
 }
+function pathToString(path) {
+  let result = "";
+  for (const key of path) {
+    if (typeof key === "number") {
+      result += `[${key}]`;
+    } else {
+      if (result.length > 0) {
+        result += ".";
+      }
+      if (key.includes("`")) {
+        throw new Error(`Invalid path key: backticks are not allowed in key "${key}"`);
+      }
+      result += key.includes(".") ? `\`${key}\`` : key;
+    }
+  }
+  return result;
+}
+function stringToPath(str) {
+  const path = [];
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ".") {
+      i++;
+      if (i >= str.length) break;
+    }
+    if (str[i] === "[") {
+      const end = str.indexOf("]", i);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing bracket in "${str}"`);
+      }
+      const num = Number(str.slice(i + 1, end));
+      if (!Number.isInteger(num) || num < 0) {
+        throw new Error(`Invalid path: non-numeric or negative index in "${str}"`);
+      }
+      path.push(num);
+      i = end + 1;
+    } else if (str[i] === "`") {
+      const end = str.indexOf("`", i + 1);
+      if (end === -1) {
+        throw new Error(`Invalid path: missing closing backtick in "${str}"`);
+      }
+      path.push(str.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      let end = i;
+      while (end < str.length && str[end] !== "." && str[end] !== "[") {
+        end++;
+      }
+      path.push(str.slice(i, end));
+      i = end;
+    }
+  }
+  return path;
+}
 function buildRestoreStructure(items) {
   const result = {};
   for (const item of items) {
@@ -502,7 +556,8 @@ function validateFormanField(field) {
 }
 function appendQueryString(path, domain, tail) {
   if (path.startsWith("api://")) return path;
-  const queryString = tail.map((part) => `${encodeURIComponent(part)}={{${part}}}`).join("&");
+  const existingParams = new Set(new URL(path).searchParams.keys());
+  const queryString = tail.filter((part) => !existingParams.has(part)).map((part) => `${encodeURIComponent(part)}={{${part}}}`).join("&");
   if (!queryString) return path;
   const separator = path.includes("?") ? "&" : "?";
   return `${path}${separator}${queryString}`;
@@ -1050,6 +1105,25 @@ async function validateFormanWithDomainsInternal(domains, options) {
       }
     );
     errors.push(...result.errors);
+    const restoreExtras = options?.states && domains[domain]?.restoreExtras;
+    if (restoreExtras) {
+      const fieldStateMap = new Map(
+        roots[domain].fieldStates.map(({ path, state }) => {
+          return [pathToString(path), state];
+        })
+      );
+      for (const [fieldPath, extra] of Object.entries(restoreExtras)) {
+        const state = fieldStateMap.get(fieldPath);
+        if (state) {
+          state.extra = extra;
+        } else {
+          roots[domain].fieldStates.push({
+            path: stringToPath(fieldPath),
+            state: { extra }
+          });
+        }
+      }
+    }
   }
   return {
     valid: errors.length === 0,
@@ -1477,11 +1551,14 @@ async function handleSelectType(value, field, context) {
       if (resolved == null || typeof resolved !== "object") {
         return {
           valid: false,
-          errors: [...errors, {
-            domain: context.domain,
-            path: context.path.join("."),
-            message: `Remote resource ${optionsOrGroups} returned no data.`
-          }]
+          errors: [
+            ...errors,
+            {
+              domain: context.domain,
+              path: context.path.join("."),
+              message: `Remote resource ${optionsOrGroups} returned no data.`
+            }
+          ]
         };
       }
       optionsOrGroups = Array.isArray(resolved) ? resolved : [resolved];
@@ -1847,8 +1924,8 @@ function toJSONSchema(field) {
 function validateFormanWithDomains(domains, options) {
   return validateFormanWithDomainsInternal(domains, options);
 }
-function validateForman(values, schema, options) {
-  return validateFormanWithDomains({ default: { values, schema } }, options);
+function validateForman(values, schema, options, restoreExtras) {
+  return validateFormanWithDomains({ default: { values, schema, restoreExtras } }, options);
 }
 export {
   toFormanSchema,

package/package.json

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