@integration-app/react 0.1.1

package/node_modules/@integration-app/sdk/src/data-builder/locators.ts

@@ -0,0 +1,702 @@
+import _ from 'lodash'
+import { toHeaderCase } from 'js-convert-case'
+import { BadRequestError } from '../errors'
+import { isEmpty } from './formulas'
+import { findSchemaOption } from '../data-schema'
+
+export enum DataLocatorStepType {
+  OBJECT_PROPERTY = 'object_property', // Points to a property inside `object` schema
+  ARRAY_ITEM = 'array_item', // Points to a specific array item by index
+  CURRENT_ARRAY_ITEM = 'current_array_item', // For cases when we iterate over a referenced array.
+  SCHEMA_OPTION = 'schema_option', // Selects schema option for anyOf schema
+}
+
+export class DataLocatorStep {
+  type: DataLocatorStepType
+}
+
+export class DataLocatorStepObjectProperty extends DataLocatorStep {
+  constructor(public propertyName: string) {
+    super()
+    this.type = DataLocatorStepType.OBJECT_PROPERTY
+  }
+}
+
+export class DataLocatorStepArrayItem extends DataLocatorStep {
+  constructor(public index: number) {
+    super()
+    this.type = DataLocatorStepType.ARRAY_ITEM
+  }
+}
+
+export class DataLocatorStepCurrentArrayItem extends DataLocatorStep {
+  constructor() {
+    super()
+    this.type = DataLocatorStepType.CURRENT_ARRAY_ITEM
+  }
+}
+
+export class DataLocatorStepSchemaOption extends DataLocatorStep {
+  constructor(public key: string) {
+    super()
+    this.type = DataLocatorStepType.SCHEMA_OPTION
+  }
+}
+
+export type DataLocator = DataLocatorStep[] | string
+
+export class InvalidLocatorError extends Error {}
+
+export function locatorToField(locator: string) {
+  if (typeof locator !== 'string') return undefined
+  return locator.replace(/^\$\./, '')
+}
+
+/*
+Extract sub-schema that pointer points at.
+*/
+export function getSchemaByLocator(schema: any, locator: DataLocator): any {
+  if (schema) {
+    try {
+      const schemaSteps = walkSchema(schema, locator)
+      if (schemaSteps) {
+        if (schemaSteps.length > 0) {
+          return schemaSteps[schemaSteps.length - 1].schema
+        } else {
+          return schema
+        }
+      } else {
+        return null
+      }
+    } catch (e) {
+      if (e instanceof InvalidLocatorError) {
+        return null
+      } else {
+        throw e
+      }
+    }
+  } else {
+    return null
+  }
+}
+
+/**
+ * Finds locators of `value` inside `data`.
+ */
+export function findValueLocators(data: any, value: any): string[] {
+  function doFindValueLocator(data: any, value: any, locatorSoFar: string) {
+    if (JSON.stringify(data) === JSON.stringify(value)) {
+      return [locatorSoFar]
+    } else {
+      if (Array.isArray(data)) {
+        const result: string[] = []
+        for (let i = 0; i < data.length; ++i) {
+          result.push(
+            ...doFindValueLocator(data[i], value, `${locatorSoFar}[${i}]`),
+          )
+        }
+        return result
+      } else if (typeof data === 'object' && data) {
+        const result: string[] = []
+        for (const key in data) {
+          result.push(
+            ...doFindValueLocator(data[key], value, `${locatorSoFar}.${key}`),
+          )
+        }
+        return result
+      } else {
+        return []
+      }
+    }
+  }
+
+  return doFindValueLocator(data, value, '$')
+}
+
+/**
+ * Returns value at a given locator in an given data object
+ */
+export function getValueAtLocator(data: any, locator: DataLocator) {
+  let curValue = data
+  const locatorSteps = locatorToSteps(locator)
+  for (let i = 0; i < locatorSteps.length; ++i) {
+    const locatorStep = locatorSteps[i]
+    switch (locatorStep.type) {
+      case DataLocatorStepType.OBJECT_PROPERTY:
+        const propStep = locatorStep as DataLocatorStepObjectProperty
+        if (
+          typeof curValue == 'object' &&
+          curValue &&
+          curValue[propStep.propertyName]
+        ) {
+          // Resolve value once in case it's lazy-loaded
+          curValue = curValue[propStep.propertyName]
+        } else {
+          return undefined
+        }
+        break
+      case DataLocatorStepType.ARRAY_ITEM:
+        const itemStep = locatorStep as DataLocatorStepArrayItem
+        if (Array.isArray(curValue) && curValue[itemStep.index]) {
+          curValue = curValue[itemStep.index]
+        } else {
+          return undefined
+        }
+        break
+      case DataLocatorStepType.CURRENT_ARRAY_ITEM:
+        if (Array.isArray(curValue)) {
+          curValue = curValue[0]
+        } else {
+          return undefined
+        }
+        break
+      case DataLocatorStepType.SCHEMA_OPTION:
+        // Do nothing - this step is only meaningful when working with schemas
+        break
+      default:
+        throw new Error(`Unknown locator step type: ${locatorStep.type}`)
+    }
+  }
+  return curValue
+}
+
+/**
+ * Sets value within a given object at the position specified by `locator`.
+ * Locator may only contain "object property" and "array index" items.
+ *
+ * Example:
+ * ```
+ * setValueAtLocator({'name': 'John'}, '$.lastName', 'Doe') == {'name': 'John', 'lastName': 'Doe'}
+ * ```
+ *
+ * More examples in tests.
+ */
+export function setValueAtLocator(obj: any, locator: string, value: any) {
+  const locatorSteps = locatorToSteps(locator)
+
+  let result = obj
+
+  if (locatorSteps.length > 0) {
+    // Current position of the locator in the object
+    let cursor = result
+    // Function we'll save a way to set value at the next step of the locator
+    let setValue: (value) => void = (value) => {
+      result = value
+    }
+
+    for (let i = 0; i < locatorSteps.length; i++) {
+      const locatorStep = locatorSteps[i]
+
+      if (
+        locatorStep instanceof DataLocatorStepArrayItem ||
+        locatorStep instanceof DataLocatorStepCurrentArrayItem
+      ) {
+        if (!Array.isArray(cursor)) {
+          // If value at locator is not array,
+          // set value at the previous locator step into an empty array
+          // and use it as cursor.
+          cursor = []
+          setValue(cursor)
+        }
+
+        const index =
+          locatorStep instanceof DataLocatorStepArrayItem
+            ? locatorStep.index
+            : 0
+
+        // Wrap function in a closure to preserve cursor
+        setValue = ((cursor) => {
+          return (value) => {
+            if (value !== undefined) {
+              cursor[index] = value
+            } else {
+              cursor.splice(index, 1)
+            }
+          }
+        })(cursor)
+
+        cursor = cursor[index]
+      } else if (locatorStep instanceof DataLocatorStepObjectProperty) {
+        if (typeof cursor !== 'object' || cursor === null) {
+          // If value at locator is not object,
+          // set value at the previous locator step into an empty object
+          // and use it as cursor.
+          cursor = {}
+          setValue(cursor)
+        }
+
+        // Wrap function in a closure to preserve cursor
+        setValue = ((cursor) => {
+          return (value) => {
+            if (value !== undefined) {
+              cursor[locatorStep.propertyName] = value
+            } else {
+              delete cursor[locatorStep.propertyName]
+            }
+          }
+        })(cursor)
+
+        cursor = cursor[locatorStep.propertyName]
+      } else {
+        throw new Error(
+          `Unexpected locator step type in "setValueAtLocator": ${locatorStep}`,
+        )
+      }
+    }
+
+    // Finally, set the value at the last step of the locator
+    setValue(value)
+
+    return result
+  } else {
+    // There are no locator steps - locator is the root object.
+    // Simply return the value
+    return value
+  }
+}
+
+/**
+ * Returns value witht `fields` locators picked from the source `value`.
+ */
+export function pickFieldsFromValue(value: any, fields: string[]): any {
+  let result
+  for (const field of fields) {
+    const fieldValue = getValueAtLocator(value, field)
+    if (!isEmpty(fieldValue)) {
+      result = setValueAtLocator(result, field, fieldValue)
+    }
+  }
+  return result
+}
+
+/**
+ * Removes `fields` from value.
+ */
+export function excludeFieldsFromValue(value: any, fields: string[]): any {
+  for (const field of fields) {
+    setValueAtLocator(value, field, undefined)
+  }
+  return value
+}
+
+/**
+ * Sets schema at a given locator into `schemaAtLocator`.
+ * Updates the passed `schema` object (if any) and returns it.
+ */
+export function setSchemaAtLocator(
+  schema: any,
+  locator: DataLocator,
+  schemaAtLocator: any,
+) {
+  const locatorSteps = locatorToSteps(locator)
+  const result = schema ?? {}
+  let curSchema = result
+  let curSchemaDataLocator = '$'
+  for (const locatorStep of locatorSteps) {
+    if (locatorStep.type == DataLocatorStepType.OBJECT_PROPERTY) {
+      curSchema.type = 'object'
+      const propertyName = (locatorStep as DataLocatorStepObjectProperty)
+        .propertyName
+      if (!curSchema.properties?.hasOwnProperty(propertyName)) {
+        curSchema.properties = {
+          ...(curSchema.properties ?? {}),
+          [propertyName]: {},
+        }
+      }
+      curSchema = curSchema.properties[propertyName]
+      curSchemaDataLocator += `.properties.${propertyName}`
+    } else if (
+      locatorStep.type == DataLocatorStepType.ARRAY_ITEM ||
+      locatorStep.type == DataLocatorStepType.CURRENT_ARRAY_ITEM
+    ) {
+      curSchema.type = 'array'
+      curSchema.items = curSchema.items ?? {}
+      curSchema = curSchema.items
+      curSchemaDataLocator = `${curSchemaDataLocator}.items`
+    } else if (locatorStep.type == DataLocatorStepType.SCHEMA_OPTION) {
+      const schemaOptionStep = locatorStep as DataLocatorStepSchemaOption
+      let schemaOption = findSchemaOption(curSchema, schemaOptionStep.key)
+      if (!schemaOption) {
+        curSchema.anyOf = curSchema.anyOf ?? []
+        schemaOption = { key: schemaOptionStep.key }
+        curSchema.anyOf.push(schemaOption)
+      }
+      curSchemaDataLocator = `${curSchemaDataLocator}.anyOf[${curSchema.anyOf.indexOf(
+        schemaOption,
+      )}]`
+      curSchema = schemaOption
+    } else {
+      throw new Error(`Unexpected locator step type: ${locatorStep.type}`)
+    }
+  }
+  return setValueAtLocator(result, curSchemaDataLocator, schemaAtLocator)
+}
+
+/**
+ * Extracts a field locator from full locator that may include formulas.
+ * For example, for locator `$.name.$concat.values[0]` returns `$.name`.
+ */
+export function extractFieldLocator(locator: string) {
+  const steps = locatorToSteps(locator)
+  const fieldSteps = []
+  for (const step of steps) {
+    if (
+      step.type === DataLocatorStepType.OBJECT_PROPERTY &&
+      (step as DataLocatorStepObjectProperty).propertyName.startsWith('$')
+    ) {
+      break
+    }
+    fieldSteps.push(step)
+  }
+  return stepsToLocator(fieldSteps)
+}
+
+/**
+ * Returns minimal JSONSchema that contains `locatorSchema` at a given locator position.
+ * For example, for locator '$.name' and locatorSchema `{type: 'string'}
+ * it will return
+ * {
+ *  type: 'object',
+ *  properties: {
+ *    name: {type: 'string'}
+ *  }
+ * }
+ */
+export function makeSchemaForLocator(
+  locator: DataLocator,
+  locatorSchema: any,
+): any {
+  return setSchemaAtLocator(null, locator, locatorSchema)
+}
+
+/*
+Get a human-readable name for a given location in a schema.
+*/
+export function getNameForLocator(schema: any, locator: DataLocator) {
+  locator = locatorToSteps(locator)
+  const schemaSteps = walkSchema(schema, locator)
+  if (schemaSteps) {
+    const titleParts = schemaSteps.map((s) => s.title).filter((t) => !!t)
+    return titleParts[titleParts.length - 1]
+  } else {
+    return null
+  }
+}
+
+export function getNameComponentsForLocator(schema: any, locator: DataLocator) {
+  locator = locatorToSteps(locator)
+  const schemaSteps = walkSchema(schema, locator)
+  return schemaSteps?.map((s) => s.title).filter((t) => !!t)
+}
+
+/*
+Get a human-readable name for the full path to the given location in a schema
+I.e. "Extracted Data > Object 1 > Field 1"
+*/
+export function getFullNameForLocator(schema: any, locator: DataLocator) {
+  return getNameComponentsForLocator(schema, locator)?.join(' > ')
+}
+
+export function getIconUriForLocator(
+  schema: any,
+  locator: DataLocator,
+): string {
+  locator = locatorToSteps(locator)
+  const schemaSteps = walkSchema(schema, locator)
+  return schemaSteps && schemaSteps.map((s) => s.iconUri).filter((t) => !!t)[0]
+}
+
+/**
+ * Checks if field locator is pointing to is user-visible.
+ * It is user-visible if no field above it has userVisible set to false.
+ */
+export function isLocatorUserVisible(
+  schema: any,
+  locator: DataLocator,
+): boolean {
+  locator = locatorToSteps(locator)
+  const schemaSteps = walkSchema(schema, locator)
+  if (schemaSteps) {
+    return !schemaSteps.some((s) => s.schema.userVisible === false)
+  } else {
+    return false
+  }
+}
+
+/**
+ * Returns a list of locators of all the fields in the data object.
+ */
+export function getLocatorsFromData(data: any, parentLocator = '$') {
+  if (data === null || data === undefined) {
+    return []
+  }
+
+  if (Array.isArray(data)) {
+    return data.flatMap((item, idx) =>
+      getLocatorsFromData(item, `${parentLocator}[${idx}]`),
+    )
+  }
+
+  if (typeof data === 'object') {
+    const locators = []
+    for (const [key, value] of Object.entries(data)) {
+      locators.push(...getLocatorsFromData(value, `${parentLocator}.${key}`))
+    }
+    return locators
+  }
+
+  return [parentLocator]
+}
+
+export function getLocatorsFromSchema(schema: any, parentLocator = '$') {
+  if (!schema || !schema.type) {
+    return []
+  }
+
+  if (schema.type === 'object') {
+    const locators = []
+    for (const [key, value] of Object.entries(schema.properties ?? {})) {
+      locators.push(...getLocatorsFromSchema(value, `${parentLocator}.${key}`))
+    }
+    return locators
+  }
+
+  if (schema.type === 'array') {
+    return getLocatorsFromSchema(schema.items, `${parentLocator}[0]`)
+  }
+
+  return [parentLocator]
+}
+
+/**
+ * @deprecated
+ */
+export const getFullTitleForLocator = getFullNameForLocator
+
+interface SchemaStep {
+  schema: any
+  title?: string
+  iconUri: string
+}
+
+export function walkSchema(schema, locator: DataLocator): SchemaStep[] {
+  locator = locatorToSteps(locator)
+  const schemaSteps: SchemaStep[] = []
+
+  let curSchema = schema
+
+  for (let idx = 0; idx < locator.length; ++idx) {
+    const schemaStep = {} as SchemaStep
+    const step = locator[idx]
+    let defaultTitle
+
+    if (!curSchema) {
+      return null
+    }
+
+    if (step.type == DataLocatorStepType.OBJECT_PROPERTY) {
+      if (curSchema.type == 'object') {
+        const objectPropertyStep = step as DataLocatorStepObjectProperty
+        curSchema = curSchema.properties?.[objectPropertyStep.propertyName]
+        defaultTitle = toHeaderCase(objectPropertyStep.propertyName)
+      } else {
+        return null
+      }
+    } else if (step.type == DataLocatorStepType.ARRAY_ITEM) {
+      if (curSchema.type == 'array') {
+        const arrayItemStep = step as DataLocatorStepArrayItem
+        curSchema = curSchema.items
+        defaultTitle = `Item #${arrayItemStep.index + 1}`
+      } else {
+        return null
+      }
+    } else if (step.type == DataLocatorStepType.CURRENT_ARRAY_ITEM) {
+      if (curSchema.type == 'array') {
+        curSchema = curSchema.items
+        defaultTitle = 'Current Item'
+      } else {
+        return null
+      }
+    } else if (step.type == DataLocatorStepType.SCHEMA_OPTION) {
+      if (curSchema.anyOf) {
+        const schemaOption = findSchemaOption(
+          curSchema,
+          (step as DataLocatorStepSchemaOption).key,
+        )
+        if (schemaOption) {
+          curSchema = schemaOption
+        } else {
+          return null
+        }
+      } else {
+        // anyOf disappeared, so what - just skip anyOf locator step
+        continue
+      }
+    }
+    if (!curSchema) {
+      // This locator is not pointing anywhere
+      return null
+    }
+    schemaStep.schema = Object.assign({}, curSchema)
+    schemaStep.title = schemaStep.schema.title ?? defaultTitle
+    schemaStep.iconUri = schemaStep.schema.iconUri
+    schemaSteps.push(schemaStep)
+  }
+
+  return schemaSteps
+}
+
+/**
+ * Transforms parameter to data locator array
+ * If parameter is already a data locator array - just return it
+ * '$.name' => [new DataLocatorObjectProperty('name')]
+ * [new DataLocatorObjectProperty('name')] => [new DataLocatorObjectProperty('name')]
+ * @param sourceLocator
+ * @returns locators
+ */
+export function locatorToSteps(sourceLocator: DataLocator): DataLocatorStep[] {
+  if (Array.isArray(sourceLocator)) return sourceLocator
+  if (typeof sourceLocator !== 'string')
+    throw new BadRequestError(
+      `Unexpected locator value: ${JSON.stringify(sourceLocator)}`,
+    )
+  if (sourceLocator === '$') return []
+
+  if (!_.startsWith(sourceLocator, '$')) {
+    sourceLocator = `$.${sourceLocator}`
+  }
+
+  const locators = []
+
+  // skip $ because it's not used for locator
+  let cursorPosition = 1
+  while (cursorPosition < sourceLocator.length) {
+    if (sourceLocator[cursorPosition] === '.') {
+      const closingIndex = _.min(
+        _.filter(
+          [
+            sourceLocator.indexOf('[', cursorPosition + 1),
+            sourceLocator.indexOf('<', cursorPosition + 1),
+            sourceLocator.indexOf('.', cursorPosition + 1),
+            sourceLocator.length,
+          ],
+          (n) => n > -1,
+        ),
+      )
+      const part = sourceLocator.slice(cursorPosition + 1, closingIndex)
+      if (!part) {
+        throw new BadRequestError('There should be a property name after a dot')
+      }
+      locators.push(
+        part === '$current'
+          ? new DataLocatorStepCurrentArrayItem()
+          : new DataLocatorStepObjectProperty(part),
+      )
+      cursorPosition = closingIndex
+    } else if (sourceLocator[cursorPosition] === '[') {
+      const closingIndex = sourceLocator.indexOf(']', cursorPosition)
+      if (closingIndex === -1) {
+        throw new BadRequestError(
+          `Could not find a closing bracket for the bracket at position ${cursorPosition}. Locator: ${sourceLocator}`,
+        )
+      }
+      const arrayIndex = +sourceLocator.slice(cursorPosition + 1, closingIndex)
+      if (isNaN(arrayIndex) || arrayIndex < 0) {
+        throw new BadRequestError(
+          `Invalid index [${sourceLocator.slice(
+            cursorPosition + 1,
+            closingIndex,
+          )}]. Index should be a positive number`,
+        )
+      }
+      locators.push(new DataLocatorStepArrayItem(arrayIndex))
+      cursorPosition = closingIndex + 1
+    } else if (sourceLocator[cursorPosition] === '<') {
+      const closingIndex = sourceLocator.indexOf('>', cursorPosition)
+      if (closingIndex === -1) {
+        throw new BadRequestError(
+          `Could not find a closing bracket for the bracket at position ${cursorPosition}. Locator: ${sourceLocator}`,
+        )
+      }
+      const optionKey = sourceLocator.slice(cursorPosition + 1, closingIndex)
+      locators.push(new DataLocatorStepSchemaOption(optionKey))
+      cursorPosition = closingIndex + 1
+    } else {
+      throw new BadRequestError(
+        `Unexpected symbol at position ${cursorPosition}. Locator: ${sourceLocator}`,
+      )
+    }
+  }
+
+  return locators
+}
+
+export function locatorToString(locator: DataLocator): string {
+  if (typeof locator === 'object' && Array.isArray(locator)) {
+    return stepsToLocator(locator)
+  } else {
+    return locator
+  }
+}
+
+export function stepsToLocator(steps: DataLocatorStep[]): string {
+  let locator = '$'
+  ;(steps ?? []).forEach((step) => {
+    switch (step.type) {
+      case DataLocatorStepType.OBJECT_PROPERTY:
+        locator += `.${(step as DataLocatorStepObjectProperty).propertyName}`
+        break
+      case DataLocatorStepType.ARRAY_ITEM:
+        locator += `[${(step as DataLocatorStepArrayItem).index}]`
+        break
+      case DataLocatorStepType.CURRENT_ARRAY_ITEM:
+        locator += '.$current'
+        break
+      case DataLocatorStepType.SCHEMA_OPTION:
+        locator += `<${(step as DataLocatorStepSchemaOption).key}>`
+        break
+      default:
+        throw new Error(`Unknown locator step type: ${step.type}`)
+    }
+  })
+  return locator
+}
+
+/**
+ * Finds locators of `$<formula>` formulas inside a data object. Returns list of locators by which these formulas can be found.
+ *
+ * For example, for
+ * {
+ *  "obj": {
+ *    "key": {
+ *       $var: $.abc
+ *    }
+ *  }
+ * }
+ * it will return ['$.obj.key']
+ */
+export function getFormulaLocators(formulaType: string, data: any): string[] {
+  function doGetFormulaLocators(data: Record<string, any>, locator: string) {
+    if (data && typeof data === 'object') {
+      if (`$${formulaType}` in data && Object.keys(data).length === 1) {
+        return [locator]
+      } else if (Array.isArray(data)) {
+        const locators = []
+        data.map((item, idx) => {
+          locators.push(...doGetFormulaLocators(item, `${locator}[${idx}]`))
+        })
+        return locators
+      } else {
+        const locators = []
+        for (const [key, value] of Object.entries(data)) {
+          locators.push(...doGetFormulaLocators(value, `${locator}.${key}`))
+        }
+        return locators
+      }
+    } else {
+      return []
+    }
+  }
+
+  return doGetFormulaLocators(data, '$')
+}