Add documentation

Author: MarekBodinger

packages/docs/docs/api-reference/utility-functions.md

@@ -1080,6 +1080,67 @@ Generates an `PathSchema` object for the `schema`, recursively
 
 - PathSchema<T> - The `PathSchema` object for the `schema`
 
+### omitExtraData<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>()
+
+The function takes a schema and formData and returns a copy of the formData with any fields not defined in the schema removed. This is useful for ensuring that only data that is relevant to the schema is preserved. Objects with `additionalProperties` keyword set to `true` will not have their extra fields removed.
+
+```ts
+const schema = {
+  type: 'object',
+  properties: {
+    child1: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    },
+    child2: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      additionalProperties: true,
+    },
+  },
+};
+
+const formData = {
+  child1: {
+    name: 'John Doe',
+    extraField: 'This should be removed',
+  },
+  child2: {
+    name: 'Jane Doe',
+    extraField: 'This should NOT be removed',
+  },
+};
+
+const filteredFormData = omitExtraData(validator, schema, schema, formData);
+console.log(filteredFormData);
+/*
+{
+  child1: {
+    name: "John Doe",
+  },
+  child2: {
+    name: "Jane Doe",
+    extraField: "This should NOT be removed",
+  },
+}
+*/
+```
+
+#### Parameters
+
+- validator: ValidatorType<T, S, F> - An implementation of the `ValidatorType` interface that will be used when necessary
+- schema: S - The schema to use for filtering the formData
+- [rootSchema]: S | undefined - The root schema, used to primarily to look up `$ref`s
+- [formData]: T | undefined - The formData to filter
+
+#### Returns
+
+- T: The new form data, with any fields not defined in the schema removed
+
 ## Schema utils creation function
 
 ### createSchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>()

packages/utils/src/createSchemaUtils.ts

@@ -277,6 +277,15 @@ class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends Fo
     return toPathSchema<T, S, F>(this.validator, schema, name, this.rootSchema, formData);
   }
 
+  /**
+   * The function takes a `schema` and `formData` and returns a copy of the formData with any fields not defined in the schema removed.
+   * This is useful for ensuring that only data that is relevant to the schema is preserved. Objects with `additionalProperties`
+   * keyword set to `true` will not have their extra fields removed.
+   *
+   * @param schema - The schema to use for filtering the `formData`
+   * @param [formData] - The formData to filter
+   * @returns The new form data, with any fields not defined in the schema removed
+   */
   omitExtraData(schema: S, formData?: T): T | undefined {
     return omitExtraData<T, S, F>(this.validator, schema, this.rootSchema, formData);
   }

packages/utils/src/schema/omitExtraData.ts

@@ -6,6 +6,13 @@ import _isEmpty from 'lodash/isEmpty';
 import toPathSchema from './toPathSchema';
 import { NAME_KEY, RJSF_ADDITONAL_PROPERTIES_FLAG } from '../constants';
 
+/**
+ * A helper function that extracts all the existing paths from the given `pathSchema` and `formData`.
+ *
+ * @param pathSchema - The `PathSchema` from which to extract the field names
+ * @param [formData] - The formData to use to determine which fields are valid
+ * @returns A list of paths represented as string arrays
+ */
 export function getFieldNames<T = any>(pathSchema: PathSchema<T>, formData?: T): string[][] {
   const getAllPaths = (_obj: GenericObjectType, acc: string[][] = [], paths: string[][] = [[]]) => {
     Object.keys(_obj).forEach((key: string) => {
@@ -38,6 +45,12 @@ export function getFieldNames<T = any>(pathSchema: PathSchema<T>, formData?: T):
   return getAllPaths(pathSchema);
 }
 
+/**
+ * A helper function to keep only the fields in the `formData` that are defined in the `fields` array.
+ *
+ * @param formData - The formData to extract the fields from
+ * @param fields - The fields to keep in the `formData`
+ */
 export function getUsedFormData<T = any>(formData: T | undefined, fields: string[][]): T | undefined {
   // For the case of a single input form
   if (fields.length === 0 && typeof formData !== 'object') {
@@ -53,6 +66,17 @@ export function getUsedFormData<T = any>(formData: T | undefined, fields: string
   return data as T;
 }
 
+/**
+ * The function takes a `schema` and `formData` and returns a copy of the formData with any fields not defined in the schema removed.
+ * This is useful for ensuring that only data that is relevant to the schema is preserved. Objects with `additionalProperties`
+ * keyword set to `true` will not have their extra fields removed.
+ *
+ * @param validator - An implementation of the `ValidatorType` interface that will be used when necessary
+ * @param schema - The schema to use for filtering the formData
+ * @param [rootSchema] - The root schema, used to primarily to look up `$ref`s
+ * @param [formData] - The formData to filter
+ * @returns The new form data, with any fields not defined in the schema removed
+ */
 export default function omitExtraData<
   T = any,
   S extends StrictRJSFSchema = RJSFSchema,