@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/flow/utils/schema-to-flow-object.ts

@@ -0,0 +1,385 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: This file processes dynamic JSON schemas
+import {
+    CallExpressionShape,
+    ObjectShape,
+    UndefinedShape,
+    type Record as FluentRecord,
+} from '@servicenow/sdk-build-core'
+import {
+    StringColumn,
+    IntegerColumn,
+    DecimalColumn,
+    BooleanColumn,
+    DateTimeColumn,
+    ChoiceColumn,
+    choiceDropdown,
+    ReferenceColumn,
+} from '@servicenow/sdk-core/runtime/db'
+import { ChoiceDropdown } from './flow-constants'
+
+/**
+ * Reverse of `generateSchemaFromObject`.
+ * Takes the `serialized_content` field from a `sys_complex_object` record and
+ * rebuilds a `FlowObject(...)` call-expression shape that can be placed back in
+ * the Fluent source.
+ */
+
+// ------------------------------------------------------------
+// Schema <-> Column API mappings (inverse of COLUMN_TYPE_TO_SCHEMA_TYPE)
+// ------------------------------------------------------------
+const SCHEMA_TYPE_TO_COLUMN_API: Record<string, string> = {
+    string: StringColumn.name,
+    integer: IntegerColumn.name,
+    number: DecimalColumn.name,
+    boolean: BooleanColumn.name,
+    date: DateTimeColumn.name,
+    glide_date_time: DateTimeColumn.name,
+    choice: ChoiceColumn.name,
+    reference: ReferenceColumn.name,
+}
+
+/**
+ * Build a `CallExpressionShape` for a simple (non-object) field given its
+ * schema primitive type and associated facets.
+ */
+function buildPrimitiveFieldCallExpr(fieldFacet: ObjectShape, source: FluentRecord): CallExpressionShape {
+    const childType = fieldFacet.get('childType').ifDefined()?.asString()?.getValue()
+    const schemaType = childType ?? fieldFacet.get('type')?.asString()?.getValue()
+    const callee = SCHEMA_TYPE_TO_COLUMN_API[schemaType] ?? StringColumn.name
+
+    const additionalProps: globalThis.Record<string, unknown> = {}
+
+    // Extract referenceTable for ReferenceColumn type
+    const referenceTable = fieldFacet.get('reference')?.ifString()?.getValue()
+    if (referenceTable && schemaType === 'reference') {
+        additionalProps['referenceTable'] = referenceTable
+    }
+
+    const isChoiceColumn = callee === ChoiceColumn.name
+    const isStringColumn = callee === StringColumn.name
+
+    return new CallExpressionShape({
+        source,
+        callee,
+        args: [
+            fieldFacet
+                .transform(({ $ }) => ({
+                    label: $.from('label', 'childLabel').map((label, child) => (child.isDefined() ? child : label)),
+                    mandatory: $.toBoolean().def(false),
+                    ...(isStringColumn && {
+                        maxLength: $.from('maxLength', 'childMaxLength')
+                            .map((maxLength, child) => {
+                                const value = child.isDefined() ? child : maxLength
+                                if (value.isString() && value.getValue() !== '') {
+                                    return value.toNumber().getValue()
+                                }
+                                return 0
+                            })
+                            .def(0),
+                    }),
+                    default: $.from('defaultValue', 'childDefaultValue')
+                        .map((defaultValue, childDefault) => (childDefault.isDefined() ? childDefault : defaultValue))
+                        .def(''),
+                    hint: $.from('hint', 'childHint')
+                        .map((hint, childHint) => (childHint.isDefined() ? childHint : hint))
+                        .def(''),
+                    ...(isChoiceColumn && {
+                        choices: $.def({}),
+                        dropdown: $.from('choiceOption')
+                            .map((value) => {
+                                const val = value.getValue()
+                                if (
+                                    value.if(UndefinedShape) ||
+                                    val === '' ||
+                                    value.toNumber().getValue() === ChoiceDropdown.DROPDOWN_WITH_NONE
+                                ) {
+                                    return undefined
+                                }
+                                return choiceDropdown[ChoiceDropdown.DROPDOWN_WITHOUT_NONE]
+                            })
+                            .def(choiceDropdown[ChoiceDropdown.DROPDOWN_WITH_NONE]),
+                    }),
+                }))
+                .merge(additionalProps),
+        ],
+    })
+}
+
+/**
+ * Recursively converts the schema representation for a FlowArray into an
+ * `ObjectShape` that will be supplied as the first argument to a
+ * `FlowArray(...)` call-expression.
+ */
+function buildFlowArrayFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const rootContent = schemaContent['$COCollectionField']
+    if (!rootContent) {
+        throw new Error('Invalid complex object schema: $COCollectionField not found')
+    }
+    let rootTypeFacet = parseTypeFacet(source, schemaContent, '$COCollectionField')
+    if (!rootTypeFacet) {
+        rootTypeFacet = parentTypeFacet
+    }
+    const type = rootTypeFacet.get('type')?.asString()?.getValue()
+    let elementType: CallExpressionShape
+    if (type === 'array.object') {
+        const childKey = parentTypeFacet.get('childName')?.asString()?.getValue()
+        elementType = buildFlowObjectFromSchema(rootContent[0][childKey], source, rootTypeFacet)
+    } else {
+        elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowArray',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                ...(complexObjectSysId ? { $id: $.val(complexObjectSysId) } : {}),
+                ...(co_type_name ? { co_type_name: $.val(co_type_name) } : {}),
+                elementType: $.val(elementType),
+                label: $.def(''),
+                mandatory: $.toBoolean().def(false),
+                hint: $.def(''),
+                maxRows: $.from('maxRows', 'max_rows')
+                    .map((maxRows, max_rows) => {
+                        const value = max_rows.isDefined() ? max_rows : maxRows
+                        if (value.isString() && value.getValue() !== '') {
+                            return value.toNumber().getValue()
+                        }
+                        return undefined
+                    })
+                    .def(undefined),
+                childName: $,
+            })),
+        ],
+    })
+}
+
+function buildNestedFlowArrayFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape
+): CallExpressionShape {
+    const type = parentTypeFacet.get('type')?.asString()?.getValue()
+    let elementType: CallExpressionShape
+    if (type === 'array.object') {
+        // Unwrap the wrapper if present (used for nested array.object)
+        // ServiceNow stores nested array.object elements in two ways:
+        // 1. With $<num>_<fieldName> wrapper (e.g., $0_task)
+        // 2. With the field name itself as wrapper (e.g., tasks inside tasks array)
+        const keys = Object.keys(schemaContent)
+        const wrapperKey = keys.find((k) => /^\$\d+_/.test(k)) ?? keys.find((k) => !k.endsWith('.$field_facets'))
+        const innerContent = wrapperKey ? schemaContent[wrapperKey] : schemaContent
+        elementType = buildFlowObjectFromSchema(innerContent, source, parentTypeFacet)
+    } else {
+        elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowArray',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                elementType: $.val(elementType),
+                label: $.def(''),
+                mandatory: $.toBoolean().def(false),
+                hint: $.def(''),
+                maxRows: $.from('maxRows', 'max_rows')
+                    .map((maxRows, max_rows) => {
+                        const value = max_rows.isDefined() ? max_rows : maxRows
+                        if (value.isString() && value.getValue() !== '') {
+                            return value.toNumber().getValue()
+                        }
+                        return undefined
+                    })
+                    .def(undefined),
+                childName: $,
+            })),
+        ],
+    })
+}
+
+/**
+ * Recursively converts the schema representation for a FlowObject into an
+ * `ObjectShape` that will be supplied as the first argument to a
+ * `FlowObject(...)` call-expression.
+ */
+function buildFlowObjectFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const properties: Record<string, unknown> = {}
+
+    if (typeof schemaContent === 'object') {
+        for (const [key, value] of Object.entries(schemaContent)) {
+            // Skip facet keys – they belong to the previous field name.
+            if (key.endsWith('.$field_facets')) {
+                continue
+            }
+
+            const fieldFacet = parseFieldFacet(source, schemaContent, key)
+            if (!fieldFacet) {
+                throw new Error(`Invalid complex object schema: ${key} facet not found`)
+            }
+            if (typeof value === 'string') {
+                // Primitive field
+                properties[key] = buildPrimitiveFieldCallExpr(fieldFacet, source)
+            } else if (typeof value === 'object' && value !== null) {
+                if (Array.isArray(value)) {
+                    // Nested FlowArray
+                    properties[key] = buildNestedFlowArrayFromSchema(value[0], source, fieldFacet)
+                } else {
+                    // Nested FlowObject
+                    properties[key] = buildFlowObjectFromSchema(value, source, fieldFacet)
+                }
+            }
+        }
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowObject',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                ...(complexObjectSysId ? { $id: $.val(complexObjectSysId) } : {}),
+                ...(co_type_name ? { co_type_name: $.val(co_type_name) } : {}),
+                fields: $.val(properties),
+                label: $.from('label', 'childLabel')
+                    .map((label, child) => (child.isDefined() ? child : label))
+                    .def(''),
+                mandatory: $.toBoolean().def(false),
+            })),
+        ],
+    })
+}
+
+/**
+ * Main entry ‑ convert `serialized_content` JSON → FlowObject or FlowArray call expression.
+ *
+ * @param schema Parsed `serialized_content`.
+ * @param source Optional source node to attach to created shapes.
+ * @param complexObjectSysId The sys_id of the sys_complex_object record (if available)
+ * @param co_type_name The name field from sys_complex_object
+ */
+export function buildComplexObjectFromSchema(
+    source: FluentRecord,
+    schema: Record<string, any>,
+    attributes: COAttributes,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const { co_type_name: attrCoTypeName, uiType, ...rest } = attributes
+    const rootKey = `FlowDesigner:${attrCoTypeName}`
+    if (!rootKey) {
+        throw new Error(`Invalid complex object schema: ${attrCoTypeName} not found`)
+    }
+    const rootContent = schema[rootKey]
+    let rootTypeFacet = parseTypeFacet(source, schema, rootKey)
+
+    if (!rootTypeFacet) {
+        throw new Error('Invalid complex object schema: root type facet not found')
+    }
+
+    rootTypeFacet = rootTypeFacet.merge({
+        type: uiType,
+        ...rest,
+    })
+    // Pass the explicit co_type_name parameter (undefined for deterministic, value for non-deterministic)
+    if (uiType.startsWith('array.')) {
+        return buildFlowArrayFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+    }
+    return buildFlowObjectFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+}
+
+function parseTypeFacet(source: FluentRecord, schema: Record<string, any>, key: string): ObjectShape | undefined {
+    const facetKey = `${key}.$type_facets`
+    return parseFacet(source, schema, facetKey)
+}
+
+function parseFieldFacet(source: FluentRecord, schema: Record<string, any>, key: string): ObjectShape | undefined {
+    const facetKey = `${key}.$field_facets`
+    return parseFacet(source, schema, facetKey)
+}
+
+function parseFacet(source: FluentRecord, schema: Record<string, any>, facetKey: string) {
+    const facet = schema[facetKey]?.SimpleMapFacet
+
+    if (!facet) {
+        return undefined
+    }
+
+    const choices = schema[facetKey]?.SimpleChoiceFacet
+
+    try {
+        const parsed = JSON.parse(facet)
+        const parsedChoices = choices ? JSON.parse(choices)['choice_map_key$'] : {}
+        return new ObjectShape({
+            source,
+            properties: {
+                type: parsed['uiType'],
+                label: parsed['label'],
+                mandatory: parsed['mandatory'],
+                reference: parsed['reference'],
+                childName: parsed['child_name'],
+                childMaxLength: parsed['child_maxsize'],
+                childHint: parsed['child_hint'],
+                maxLength: parsed['max_length'],
+                maxRows: parsed['max_rows'],
+                childType: parsed['child_type'],
+                childLabel: parsed['child_label'],
+                choiceOption: parsed['choiceOption'],
+                defaultValue: parsed['default_value'],
+                childDefaultValue: parsed['child_defaultValue'],
+                hint: parsed['hint'],
+                choices: Object.keys(parsedChoices).reduce(
+                    (acc, key) => {
+                        const { label, value, order } = JSON.parse(parsedChoices[key])
+                        acc[value] = { label, sequence: order }
+                        return acc
+                    },
+                    {} as globalThis.Record<string, { label: string; sequence: number }>
+                ),
+            },
+        })
+    } catch {
+        // Failed to parse facet - returning undefined
+    }
+
+    return undefined
+}
+
+export function getAttributeValue(attributesStr: string, key: string): string | undefined {
+    const attributes = parseAttributesToObject(attributesStr)
+    return attributes[key]
+}
+
+type COAttributes = {
+    dynamic: string
+    co_type_name: string
+    uiType: string
+    child_label?: string
+    child_name?: string
+    child_type?: string
+    [key: string]: string | undefined
+}
+
+export function parseAttributesToObject(attributesStr: string): COAttributes {
+    return attributesStr
+        .split(',')
+        .map((p) => p.trim())
+        .reduce((acc, pair) => {
+            const [key, value] = pair.split('=')
+            if (key && value !== undefined) {
+                acc[key as keyof COAttributes] = value
+            }
+            return acc
+        }, {} as COAttributes)
+}