@rjsf/utils 5.11.2 → 5.12.0

package/src/labelValue.ts

@@ -0,0 +1,16 @@
+import { ReactElement } from 'react';
+
+/** Helper function that will return the value to use for a widget `label` based on `hideLabel`. The `fallback` is used
+ * as the return value from the function when `hideLabel` is true. Due to the implementation of theme components, it
+ * may be necessary to return something other than `undefined` to cause the theme component to not render a label. Some
+ * themes require may `false` and others may require an empty string.
+ *
+ * @param [label] - The label string or component to render when not hidden
+ * @param [hideLabel] - Flag, if true, will cause the label to be hidden
+ * @param [fallback] - One of 3 values, `undefined` (the default), `false` or an empty string
+ * @returns - `fallback` if `hideLabel` is true, otherwise `label`
+ */
+export function labelValue(label?: string | ReactElement, hideLabel?: boolean, fallback?: ''): undefined | string;
+export default function labelValue(label?: string | ReactElement, hideLabel?: boolean, fallback?: false | '') {
+  return hideLabel ? fallback : label;
+}

package/src/localToUTC.ts

@@ -0,0 +1,8 @@
+/** Converts a local Date string into a UTC date string
+ *
+ * @param dateString - The string representation of a date as accepted by the `Date()` constructor
+ * @returns - A UTC date string if `dateString` is truthy, otherwise undefined
+ */
+export default function localToUTC(dateString: string) {
+  return dateString ? new Date(dateString).toJSON() : undefined;
+}

package/src/mergeDefaultsWithFormData.ts

@@ -0,0 +1,53 @@
+import get from 'lodash/get';
+
+import isObject from './isObject';
+import { GenericObjectType } from '../src';
+
+/** Merges the `defaults` object of type `T` into the `formData` of type `T`
+ *
+ * When merging defaults and form data, we want to merge in this specific way:
+ * - objects are deeply merged
+ * - arrays are merged in such a way that:
+ *   - when the array is set in form data, only array entries set in form data
+ *     are deeply merged; additional entries from the defaults are ignored unless `mergeExtraArrayDefaults` is true, in
+ *     which case the extras are appended onto the end of the form data
+ *   - when the array is not set in form data, the default is copied over
+ * - scalars are overwritten/set by form data
+ *
+ * @param [defaults] - The defaults to merge
+ * @param [formData] - The form data into which the defaults will be merged
+ * @param [mergeExtraArrayDefaults=false] - If true, any additional default array entries are appended onto the formData
+ * @returns - The resulting merged form data with defaults
+ */
+export default function mergeDefaultsWithFormData<T = any>(
+  defaults?: T,
+  formData?: T,
+  mergeExtraArrayDefaults = false
+): T | undefined {
+  if (Array.isArray(formData)) {
+    const defaultsArray = Array.isArray(defaults) ? defaults : [];
+    const mapped = formData.map((value, idx) => {
+      if (defaultsArray[idx]) {
+        return mergeDefaultsWithFormData<any>(defaultsArray[idx], value, mergeExtraArrayDefaults);
+      }
+      return value;
+    });
+    // Merge any extra defaults when mergeExtraArrayDefaults is true
+    if (mergeExtraArrayDefaults && mapped.length < defaultsArray.length) {
+      mapped.push(...defaultsArray.slice(mapped.length));
+    }
+    return mapped as unknown as T;
+  }
+  if (isObject(formData)) {
+    const acc: { [key in keyof T]: any } = Object.assign({}, defaults); // Prevent mutation of source object.
+    return Object.keys(formData as GenericObjectType).reduce((acc, key) => {
+      acc[key as keyof T] = mergeDefaultsWithFormData<T>(
+        defaults ? get(defaults, key) : {},
+        get(formData, key),
+        mergeExtraArrayDefaults
+      );
+      return acc;
+    }, acc);
+  }
+  return formData;
+}

package/src/mergeObjects.ts

@@ -0,0 +1,39 @@
+import isObject from './isObject';
+import { GenericObjectType } from './types';
+
+/** Recursively merge deeply nested objects.
+ *
+ * @param obj1 - The first object to merge
+ * @param obj2 - The second object to merge
+ * @param [concatArrays=false] - Optional flag that, when true, will cause arrays to be concatenated. Use
+ *          "preventDuplicates" to merge arrays in a manner that prevents any duplicate entries from being merged.
+ *          NOTE: Uses shallow comparison for the duplicate checking.
+ * @returns - A new object that is the merge of the two given objects
+ */
+export default function mergeObjects(
+  obj1: GenericObjectType,
+  obj2: GenericObjectType,
+  concatArrays: boolean | 'preventDuplicates' = false
+) {
+  return Object.keys(obj2).reduce((acc, key) => {
+    const left = obj1 ? obj1[key] : {},
+      right = obj2[key];
+    if (obj1 && key in obj1 && isObject(right)) {
+      acc[key] = mergeObjects(left, right, concatArrays);
+    } else if (concatArrays && Array.isArray(left) && Array.isArray(right)) {
+      let toMerge = right;
+      if (concatArrays === 'preventDuplicates') {
+        toMerge = right.reduce((result, value) => {
+          if (!left.includes(value)) {
+            result.push(value);
+          }
+          return result;
+        }, []);
+      }
+      acc[key] = left.concat(toMerge);
+    } else {
+      acc[key] = right;
+    }
+    return acc;
+  }, Object.assign({}, obj1)); // Prevent mutation of source object.
+}

package/src/mergeSchemas.ts

@@ -0,0 +1,38 @@
+import union from 'lodash/union';
+
+import { REQUIRED_KEY } from './constants';
+import getSchemaType from './getSchemaType';
+import isObject from './isObject';
+import { GenericObjectType } from './types';
+
+/** Recursively merge deeply nested schemas. The difference between `mergeSchemas` and `mergeObjects` is that
+ * `mergeSchemas` only concats arrays for values under the 'required' keyword, and when it does, it doesn't include
+ * duplicate values.
+ *
+ * @param obj1 - The first schema object to merge
+ * @param obj2 - The second schema object to merge
+ * @returns - The merged schema object
+ */
+export default function mergeSchemas(obj1: GenericObjectType, obj2: GenericObjectType) {
+  const acc = Object.assign({}, obj1); // Prevent mutation of source object.
+  return Object.keys(obj2).reduce((acc, key) => {
+    const left = obj1 ? obj1[key] : {},
+      right = obj2[key];
+    if (obj1 && key in obj1 && isObject(right)) {
+      acc[key] = mergeSchemas(left, right);
+    } else if (
+      obj1 &&
+      obj2 &&
+      (getSchemaType(obj1) === 'object' || getSchemaType(obj2) === 'object') &&
+      key === REQUIRED_KEY &&
+      Array.isArray(left) &&
+      Array.isArray(right)
+    ) {
+      // Don't include duplicate values when merging 'required' fields.
+      acc[key] = union(left, right);
+    } else {
+      acc[key] = right;
+    }
+    return acc;
+  }, acc);
+}

package/src/optionsList.ts

@@ -0,0 +1,41 @@
+import toConstant from './toConstant';
+import { RJSFSchema, EnumOptionsType, StrictRJSFSchema } from './types';
+
+/** Gets the list of options from the schema. If the schema has an enum list, then those enum values are returned. The
+ * labels for the options will be extracted from the non-standard, RJSF-deprecated `enumNames` if it exists, otherwise
+ * the label will be the same as the `value`. If the schema has a `oneOf` or `anyOf`, then the value is the list of
+ * `const` values from the schema and the label is either the `schema.title` or the value.
+ *
+ * @param schema - The schema from which to extract the options list
+ * @returns - The list of options from the schema
+ */
+export default function optionsList<S extends StrictRJSFSchema = RJSFSchema>(
+  schema: S
+): EnumOptionsType<S>[] | undefined {
+  // enumNames was deprecated in v5 and is intentionally omitted from the RJSFSchema type.
+  // Cast the type to include enumNames so the feature still works.
+  const schemaWithEnumNames = schema as S & { enumNames?: string[] };
+  if (schemaWithEnumNames.enumNames && process.env.NODE_ENV !== 'production') {
+    console.warn('The enumNames property is deprecated and may be removed in a future major release.');
+  }
+  if (schema.enum) {
+    return schema.enum.map((value, i) => {
+      const label = (schemaWithEnumNames.enumNames && schemaWithEnumNames.enumNames[i]) || String(value);
+      return { label, value };
+    });
+  }
+  const altSchemas = schema.oneOf || schema.anyOf;
+  return (
+    altSchemas &&
+    altSchemas.map((aSchemaDef) => {
+      const aSchema = aSchemaDef as S;
+      const value = toConstant(aSchema);
+      const label = aSchema.title || String(value);
+      return {
+        schema: aSchema,
+        label,
+        value,
+      };
+    })
+  );
+}

package/src/orderProperties.ts

@@ -0,0 +1,44 @@
+import { GenericObjectType } from './types';
+
+/** Given a list of `properties` and an `order` list, returns a list that contains the `properties` ordered correctly.
+ * If `order` is not an array, then the untouched `properties` list is returned. Otherwise `properties` is ordered per
+ * the `order` list. If `order` contains a '*' then any `properties` that are not mentioned explicity in `order` will be
+ * places in the location of the `*`.
+ *
+ * @param properties - The list of property keys to be ordered
+ * @param order - An array of property keys to be ordered first, with an optional '*' property
+ * @returns - A list with the `properties` ordered
+ * @throws - Error when the properties cannot be ordered correctly
+ */
+export default function orderProperties(properties: string[], order?: string[]): string[] {
+  if (!Array.isArray(order)) {
+    return properties;
+  }
+
+  const arrayToHash = (arr: string[]) =>
+    arr.reduce((prev: GenericObjectType, curr) => {
+      prev[curr] = true;
+      return prev;
+    }, {});
+  const errorPropList = (arr: string[]) =>
+    arr.length > 1 ? `properties '${arr.join("', '")}'` : `property '${arr[0]}'`;
+  const propertyHash = arrayToHash(properties);
+  const orderFiltered = order.filter((prop) => prop === '*' || propertyHash[prop]);
+  const orderHash = arrayToHash(orderFiltered);
+
+  const rest = properties.filter((prop: string) => !orderHash[prop]);
+  const restIndex = orderFiltered.indexOf('*');
+  if (restIndex === -1) {
+    if (rest.length) {
+      throw new Error(`uiSchema order list does not contain ${errorPropList(rest)}`);
+    }
+    return orderFiltered;
+  }
+  if (restIndex !== orderFiltered.lastIndexOf('*')) {
+    throw new Error('uiSchema order list contains more than one wildcard item');
+  }
+
+  const complete = [...orderFiltered];
+  complete.splice(restIndex, 1, ...rest);
+  return complete;
+}

package/src/pad.ts

@@ -0,0 +1,13 @@
+/** Returns a string representation of the `num` that is padded with leading "0"s if necessary
+ *
+ * @param num - The number to pad
+ * @param width - The width of the string at which no lead padding is necessary
+ * @returns - The number converted to a string with leading zero padding if the number of digits is less than `width`
+ */
+export default function pad(num: number, width: number) {
+  let s = String(num);
+  while (s.length < width) {
+    s = '0' + s;
+  }
+  return s;
+}

package/src/parseDateString.ts

@@ -0,0 +1,33 @@
+import { DateObject } from './types';
+
+/** Parses the `dateString` into a `DateObject`, including the time information when `includeTime` is true
+ *
+ * @param dateString - The date string to parse into a DateObject
+ * @param [includeTime=true] - Optional flag, if false, will not include the time data into the object
+ * @returns - The date string converted to a `DateObject`
+ * @throws - Error when the date cannot be parsed from the string
+ */
+export default function parseDateString(dateString?: string, includeTime = true): DateObject {
+  if (!dateString) {
+    return {
+      year: -1,
+      month: -1,
+      day: -1,
+      hour: includeTime ? -1 : 0,
+      minute: includeTime ? -1 : 0,
+      second: includeTime ? -1 : 0,
+    };
+  }
+  const date = new Date(dateString);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error('Unable to parse date ' + dateString);
+  }
+  return {
+    year: date.getUTCFullYear(),
+    month: date.getUTCMonth() + 1, // oh you, javascript.
+    day: date.getUTCDate(),
+    hour: includeTime ? date.getUTCHours() : 0,
+    minute: includeTime ? date.getUTCMinutes() : 0,
+    second: includeTime ? date.getUTCSeconds() : 0,
+  };
+}

package/src/parser/ParserValidator.ts

@@ -0,0 +1,132 @@
+import get from 'lodash/get';
+import isEqual from 'lodash/isEqual';
+
+import { ID_KEY } from '../constants';
+import hashForSchema from '../hashForSchema';
+import {
+  CustomValidator,
+  ErrorSchema,
+  ErrorTransformer,
+  FormContextType,
+  RJSFSchema,
+  RJSFValidationError,
+  StrictRJSFSchema,
+  UiSchema,
+  ValidationData,
+  ValidatorType,
+} from '../types';
+
+/** The type of the map of schema hash to schema
+ */
+export type SchemaMap<S extends StrictRJSFSchema = RJSFSchema> = {
+  [hash: string]: S;
+};
+
+/** An implementation of the `ValidatorType` interface that is designed for use in capturing schemas used by the
+ * `isValid()` function. The rest of the implementation of the interface throws errors when it is attempted to be used.
+ * An instance of the object allows the caller to capture the schemas used in calls to the `isValid()` function. These
+ * captured schema, along with the root schema used to construct the object are stored in the map of schemas keyed by
+ * the hashed value of the schema. NOTE: After hashing the schema, an $id with the hash value is added to the
+ * schema IF that schema doesn't already have an $id, prior to putting the schema into the map.
+ */
+export default class ParserValidator<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
+  implements ValidatorType<T, S, F>
+{
+  /** The rootSchema provided during construction of the class */
+  readonly rootSchema: S;
+
+  /** The map of schemas encountered by the ParserValidator */
+  schemaMap: SchemaMap<S> = {};
+
+  /** Construct the ParserValidator for the given `rootSchema`. This `rootSchema` will be stashed in the `schemaMap`
+   * first.
+   *
+   * @param rootSchema - The root schema against which this validator will be executed
+   */
+  constructor(rootSchema: S) {
+    this.rootSchema = rootSchema;
+    this.addSchema(rootSchema, hashForSchema<S>(rootSchema));
+  }
+
+  /** Adds the given `schema` to the `schemaMap` keyed by the `hash` or `ID_KEY` if present on the `schema`. If the
+   * schema does not have an `ID_KEY`, then the `hash` will be added as the `ID_KEY` to allow the schema to be
+   * associated with it's `hash` for future use (by a schema compiler).
+   *
+   * @param schema - The schema which is to be added to the map
+   * @param hash - The hash value at which to map the schema
+   */
+  addSchema(schema: S, hash: string) {
+    const key = get(schema, ID_KEY, hash);
+    const identifiedSchema = { ...schema, [ID_KEY]: key };
+    const existing = this.schemaMap[key];
+    if (!existing) {
+      this.schemaMap[key] = identifiedSchema;
+    } else if (!isEqual(existing, identifiedSchema)) {
+      console.error('existing schema:', JSON.stringify(existing, null, 2));
+      console.error('new schema:', JSON.stringify(identifiedSchema, null, 2));
+      throw new Error(
+        `Two different schemas exist with the same key ${key}! What a bad coincidence. If possible, try adding an $id to one of the schemas`
+      );
+    }
+  }
+
+  /** Returns the current `schemaMap` to the caller
+   */
+  getSchemaMap() {
+    return this.schemaMap;
+  }
+
+  /** Implements the `ValidatorType` `isValid()` method to capture the `schema` in the `schemaMap`. Throws an error when
+   * the `rootSchema` is not the same as the root schema provided during construction.
+   *
+   * @param schema - The schema to record in the `schemaMap`
+   * @param _formData - The formData parameter that is ignored
+   * @param rootSchema - The root schema associated with the schema
+   * @throws - Error when the given `rootSchema` differs from the root schema provided during construction
+   */
+  isValid(schema: S, _formData: T, rootSchema: S): boolean {
+    if (!isEqual(rootSchema, this.rootSchema)) {
+      throw new Error('Unexpectedly calling isValid() with a rootSchema that differs from the construction rootSchema');
+    }
+    this.addSchema(schema, hashForSchema<S>(schema));
+
+    return false;
+  }
+
+  /** Implements the `ValidatorType` `rawValidation()` method to throw an error since it is never supposed to be called
+   *
+   * @param _schema - The schema parameter that is ignored
+   * @param _formData - The formData parameter that is ignored
+   */
+  rawValidation<Result = any>(_schema: S, _formData?: T): { errors?: Result[]; validationError?: Error } {
+    throw new Error('Unexpectedly calling the `rawValidation()` method during schema parsing');
+  }
+
+  /** Implements the `ValidatorType` `toErrorList()` method to throw an error since it is never supposed to be called
+   *
+   * @param _errorSchema - The error schema parameter that is ignored
+   * @param _fieldPath - The field path parameter that is ignored
+   */
+  toErrorList(_errorSchema?: ErrorSchema<T>, _fieldPath?: string[]): RJSFValidationError[] {
+    throw new Error('Unexpectedly calling the `toErrorList()` method during schema parsing');
+  }
+
+  /** Implements the `ValidatorType` `validateFormData()` method to throw an error since it is never supposed to be
+   * called
+   *
+   * @param _formData - The formData parameter that is ignored
+   * @param _schema - The schema parameter that is ignored
+   * @param _customValidate - The customValidate parameter that is ignored
+   * @param _transformErrors - The transformErrors parameter that is ignored
+   * @param _uiSchema - The uiSchema parameter that is ignored
+   */
+  validateFormData(
+    _formData: T,
+    _schema: S,
+    _customValidate?: CustomValidator<T, S, F>,
+    _transformErrors?: ErrorTransformer<T, S, F>,
+    _uiSchema?: UiSchema<T, S, F>
+  ): ValidationData<T> {
+    throw new Error('Unexpectedly calling the `validateFormData()` method during schema parsing');
+  }
+}

package/src/parser/index.ts

@@ -0,0 +1,6 @@
+import schemaParser from './schemaParser';
+import { SchemaMap } from './ParserValidator';
+
+export type { SchemaMap };
+
+export { schemaParser };

package/src/parser/schemaParser.ts

@@ -0,0 +1,60 @@
+import forEach from 'lodash/forEach';
+import isEqual from 'lodash/isEqual';
+
+import { FormContextType, RJSFSchema, StrictRJSFSchema } from '../types';
+import { PROPERTIES_KEY, ITEMS_KEY } from '../constants';
+import ParserValidator, { SchemaMap } from './ParserValidator';
+import { retrieveSchemaInternal, resolveAnyOrOneOfSchemas } from '../schema/retrieveSchema';
+
+/** Recursive function used to parse the given `schema` belonging to the `rootSchema`. The `validator` is used to
+ * capture the sub-schemas that the `isValid()` function is called with. For each schema returned by the
+ * `retrieveSchemaInternal()`, the `resolveAnyOrOneOfSchemas()` function is called. For each of the schemas returned
+ * from THAT call have `properties`, then each of the sub-schema property objects are then recursively parsed.
+ *
+ * @param validator - The `ParserValidator` implementation used to capture `isValid()` calls during parsing
+ * @param recurseList - The list of schemas returned from the `retrieveSchemaInternal`, preventing infinite recursion
+ * @param rootSchema - The root schema from which the schema parsing began
+ * @param schema - The current schema element being parsed
+ */
+function parseSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
+  validator: ParserValidator<T, S, F>,
+  recurseList: S[],
+  rootSchema: S,
+  schema: S
+) {
+  const schemas = retrieveSchemaInternal<T, S, F>(validator, schema, rootSchema, undefined, true);
+  schemas.forEach((schema) => {
+    const sameSchemaIndex = recurseList.findIndex((item) => isEqual(item, schema));
+    if (sameSchemaIndex === -1) {
+      recurseList.push(schema);
+      const allOptions = resolveAnyOrOneOfSchemas<T, S, F>(validator, schema, rootSchema, true);
+      allOptions.forEach((s) => {
+        if (PROPERTIES_KEY in s && s[PROPERTIES_KEY]) {
+          forEach(schema[PROPERTIES_KEY], (value) => {
+            parseSchema<T, S, F>(validator, recurseList, rootSchema, value as S);
+          });
+        }
+      });
+      if (ITEMS_KEY in schema && !Array.isArray(schema.items) && typeof schema.items !== 'boolean') {
+        parseSchema<T, S, F>(validator, recurseList, rootSchema, schema.items as S);
+      }
+    }
+  });
+}
+
+/** Parses the given `rootSchema` to extract out all the sub-schemas that maybe contained within it. Returns a map of
+ * the hash of the schema to schema/sub-schema.
+ *
+ * @param rootSchema - The root schema to parse for sub-schemas used by `isValid()` calls
+ * @returns - The `SchemaMap` of all schemas that were parsed
+ */
+export default function schemaParser<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
+  rootSchema: S
+): SchemaMap<S> {
+  const validator = new ParserValidator<T, S, F>(rootSchema);
+  const recurseList: S[] = [];
+
+  parseSchema(validator, recurseList, rootSchema, rootSchema);
+
+  return validator.getSchemaMap();
+}

package/src/rangeSpec.ts

@@ -0,0 +1,22 @@
+import { RangeSpecType, StrictRJSFSchema } from './types';
+import { RJSFSchema } from './types';
+
+/** Extracts the range spec information `{ step?: number, min?: number, max?: number }` that can be spread onto an HTML
+ * input from the range analog in the schema `{ multipleOf?: number, minimum?: number, maximum?: number }`.
+ *
+ * @param schema - The schema from which to extract the range spec
+ * @returns - A range specification from the schema
+ */
+export default function rangeSpec<S extends StrictRJSFSchema = RJSFSchema>(schema: S) {
+  const spec: RangeSpecType = {};
+  if (schema.multipleOf) {
+    spec.step = schema.multipleOf;
+  }
+  if (schema.minimum || schema.minimum === 0) {
+    spec.min = schema.minimum;
+  }
+  if (schema.maximum || schema.maximum === 0) {
+    spec.max = schema.maximum;
+  }
+  return spec;
+}

package/src/replaceStringParameters.ts

@@ -0,0 +1,22 @@
+/** Potentially substitutes all replaceable parameters with the associated value(s) from the `params` if available. When
+ * a `params` array is provided, each value in the array is used to replace any of the replaceable parameters in the
+ * `inputString` using the `%1`, `%2`, etc. replacement specifiers.
+ *
+ * @param inputString - The string which will be potentially updated with replacement parameters
+ * @param params - The optional list of replaceable parameter values to substitute into the english string
+ * @returns - The updated string with any replacement specifiers replaced
+ */
+export default function replaceStringParameters(inputString: string, params?: string[]) {
+  let output = inputString;
+  if (Array.isArray(params)) {
+    const parts = output.split(/(%\d)/);
+    params.forEach((param, index) => {
+      const partIndex = parts.findIndex((part) => part === `%${index + 1}`);
+      if (partIndex >= 0) {
+        parts[partIndex] = param;
+      }
+    });
+    output = parts.join('');
+  }
+  return output;
+}