@servicenow/sdk-build-plugins 2.0.1

package/src/scriptedRESTAPI/RestUtils.ts

@@ -0,0 +1,507 @@
+/* eslint-disable no-case-declarations */
+import * as ts from 'ts-morph'
+import {
+    Context,
+    Document,
+    Result,
+    DocumentPointer,
+    removeNode,
+    getCallExpressionName,
+    Arranged,
+    UnlinkedDocument,
+    getNodeId,
+} from '@servicenow/sdk-build-core'
+import { isEqual } from 'lodash'
+import { RestApi } from '@servicenow/sdk-core/runtime/rest'
+import { RecordPlugin } from '../db/RecordPlugin'
+
+export const restTables = [
+    'sys_ws_definition',
+    'sys_ws_operation',
+    'sys_ws_version',
+    'sys_ws_header',
+    'sys_ws_query_parameter',
+    'sys_ws_header_map',
+    'sys_ws_query_parameter_map',
+]
+
+let restDocumentMap: any = undefined
+
+/** checks if a given query_parameter or header doc is consumed by the given rest or not in current transformation*/
+const isConsumedByRest = (restId: string, restDocMap: any, document: Document) => {
+    if (restDocMap[restId] && restDocMap[restId].route_attrs_map) {
+        const found = Object.values(restDocMap[restId].route_attrs_map).find(
+            (doc: any) =>
+                doc.data['data'].web_service_query_parameter === document.guid ||
+                doc.data['data'].web_service_header === document.guid
+        )
+        return found ? true : false
+    }
+    return false
+}
+
+export function getRouteAttrMapResult(document: Document, restDocMap: any): Result<DocumentPointer | undefined> {
+    if (document.action === 'DELETE') {
+        return { handled: false }
+    }
+    /**
+     * if the given attribute map record references query parameter or routes record
+     * not part of the current app we make it a record call.
+     */
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    if (isUnHandled) {
+        return { handled: false }
+    }
+
+    const routeId = document.data!['data']['web_service_operation']
+    const paramField =
+        document.data!['table'] === 'sys_ws_header_map' ? 'web_service_header' : 'web_service_query_parameter'
+    potentialRecordCallRouteParams.delete(document.data!['data'][paramField])
+    /** if the attribute map record is consumed by any rest then associated appropriate parent */
+    return { handled: true, result: { kind: 'record', guid: routeId } }
+}
+
+/** utility function to get the args node of a call expression node*/
+export const getArgs = (document: Document) => {
+    const node = document.node!.asKindOrThrow(ts.SyntaxKind.CallExpression)
+    return node.getArguments()[0]!.asKindOrThrow(ts.SyntaxKind.ObjectLiteralExpression)
+}
+
+/**
+ * utility function that iterates over all the headers or parameters of all routes
+ * inside a rest api and calls the provided callback function.
+ */
+export function iterateAllRouteAttrNode(
+    document: Document,
+    eleAttrName: string,
+    callback: (
+        expression: ts.ArrayLiteralExpression,
+        element: ts.Expression,
+        compositeKey: { attr: string; route: string; rest: string }
+    ) => void
+) {
+    const argsNode = getArgs(document)
+    const restId = getNodeId(argsNode)!
+    argsNode
+        .getProperty('routes')
+        ?.asKind(ts.ts.SyntaxKind.PropertyAssignment)
+        ?.getInitializerIfKindOrThrow(ts.ts.SyntaxKind.ArrayLiteralExpression)
+        ?.getElements()
+        .forEach((element) => {
+            const routeId = getNodeId(element.asKindOrThrow(ts.SyntaxKind.ObjectLiteralExpression))!
+            const arrayExpression = element
+                .asKind(ts.ts.SyntaxKind.ObjectLiteralExpression)
+                ?.getProperty(eleAttrName)
+                ?.asKind(ts.ts.SyntaxKind.PropertyAssignment)
+                ?.getInitializerIfKindOrThrow(ts.ts.SyntaxKind.ArrayLiteralExpression)
+
+            arrayExpression?.getElements().forEach((element) => {
+                const attrId = getNodeId(element.asKindOrThrow(ts.SyntaxKind.ObjectLiteralExpression))!
+                callback(arrayExpression, element, {
+                    attr: attrId,
+                    route: routeId,
+                    rest: restId,
+                })
+            })
+        })
+}
+
+/**
+ * keeps track of all those params records associated with a rest node,
+ * so if some m2m records removes all its associations then we would create record call.
+ */
+export const potentialRecordCallRouteParams = new Set<string>()
+/**
+ * There are some of the completely unassociated param records generated when an
+ * m2m record swtiches from one rest to another rest entity. we track them to generate records calls
+ * if required.
+ */
+export const completelyUnassociatedParamIds = new Set<string>()
+/**
+ * Ids of records which are going to be a record call so need not handle them in rest generator.
+ */
+export const unHandledIds: string[] = []
+
+/** Based on the result it adds the document id to unHandledIds which is later on used by generator
+ *  to avoid generating nodes for them since it's expected to be handled by record plugin.
+ */
+export function handleAndReturnResult(result: Result<DocumentPointer | undefined>, document: Document) {
+    if (!result.handled) {
+        unHandledIds.push(document.guid)
+    }
+    return result
+}
+
+/**
+ * Performs the following operations:
+ * 1. If the documents associated rest node is the same as the referenced rest in data, let the rest node handle it.
+ * 2. If it refernces a different rest node, then clean up the current rest node and its keys. If the referenced rest node
+ *    has a mapping record to consume this parameter or header let it handle, else make it a record call.
+ */
+export function getRouteAttrWithRestNodeResult(
+    document: Document,
+    context: Context,
+    restDocMap: any
+): Result<DocumentPointer | undefined> {
+    const restId = document.data!['data']['web_service_definition']
+    const nodeId = getNodeId(getArgs(document))!
+    const nodeRestId = context.keys.explicit[nodeId]!.id
+    if (document.action === 'DELETE') {
+        return { handled: true, result: { kind: 'record', guid: nodeRestId } }
+    }
+    if (restId === nodeRestId) {
+        return { handled: true, result: { kind: 'record', guid: restId } }
+    }
+    const attrName = document.data!['table'] === 'sys_ws_header' ? 'headers' : 'parameters'
+    let deleteAttrKey: string | undefined = undefined
+    iterateAllRouteAttrNode(document, attrName, (arrayExp, element, compKey) => {
+        const attrSysId = context.keys.explicit[compKey.attr]!.id
+        if (attrSysId === document.guid) {
+            deleteAttrKey = compKey.attr
+            const idx = context.keys.composite.findIndex((k) => isEqual(k.key, compKey))
+            if (idx !== -1) {
+                context.keys.composite.splice(idx, 1)
+            }
+            arrayExp.removeElement(element)
+        }
+    })
+    if (deleteAttrKey) {
+        delete context.keys.explicit[deleteAttrKey]
+    }
+    potentialRecordCallRouteParams.delete(document.guid)
+    deleteDocNode(document, context)
+    document['changedData'] = { data: document.data!['data'] }
+    if (!isConsumed(document, restDocMap)) {
+        return { handled: false }
+    }
+    return { handled: true, result: { kind: 'record', guid: restId } }
+}
+
+function isConsumed(document: Document, restDocMap: any) {
+    const restId = document.data!['data']['web_service_definition']
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    if (isUnHandled) {
+        return false
+    }
+
+    return isConsumedByRest(restId, restDocMap, document)
+}
+
+/**
+ * Deletes node reference from document and updates in context docs as well to keep it updated.
+ */
+const deleteDocNode = (document: Document, context: Context) => {
+    const foundDoc = context.getAllDocuments().find((doc) => doc.guid === document.guid)
+    delete foundDoc?.node
+    delete document.node
+}
+
+/**
+ * checks to see if the document is consumed by any rest api. If consumed then
+ * remove that record call expression and its associated keys and let rest handle
+ * it, else update the record call.
+ */
+export function getRouteAttrWithRecordNodeResult(
+    document: Document,
+    context: Context,
+    restDocMap: any
+): Result<DocumentPointer | undefined> {
+    if (document.action === 'DELETE') {
+        return { handled: false }
+    }
+    if (!isConsumed(document, restDocMap)) {
+        return { handled: false }
+    }
+    const recordId = getNodeId(getArgs(document))!
+    removeNode(document.node!)
+    deleteDocNode(document, context)
+    delete context.keys.explicit[recordId]
+    document['changedData'] = { data: document.data!['data'] }
+    return { handled: true, result: { kind: 'record', guid: document.data!['data']['web_service_definition'] } }
+}
+
+/** Gets the rest id for the given route id.*/
+const getRestIdForRoute = (routeId: string, restDocMap: any) => {
+    let restId: string | undefined = undefined
+    Object.keys(restDocMap)
+        .filter((key) => key !== 'unHanlded_records' && key !== 'delete_records')
+        .forEach((key) => {
+            if (restDocMap[key].routes) {
+                const foundRoute = Object.values(restDocMap[key].routes).find((doc: any) => doc.id === routeId)
+                if (foundRoute) {
+                    restId = key
+                }
+            }
+        })
+    return restId
+}
+
+/** cleans the mapping node from given array and keys file*/
+const cleanMapDocInNode = (
+    arrayExp: ts.ArrayLiteralExpression,
+    element: ts.Expression,
+    compKey: { attr: string; route: string; rest: string },
+    context: Context,
+    document: Document
+) => {
+    const idx = context.keys.composite.findIndex((k) => isEqual(k.key, compKey))
+    if (idx !== -1) {
+        const compObj = context.keys.composite[idx]
+        if (compObj?.id === document.guid) {
+            arrayExp.removeElement(element)
+            context.keys.composite.splice(idx, 1)
+            return context.keys.explicit[compKey.attr]?.id
+        }
+    }
+    return undefined
+}
+
+/**
+ * Performs the following operations:
+ * 1. If the mapping record references a differnt route or query param not part of the app
+ *    then clean its presence from current rest node and create a record call for it.
+ * 2. If if references a different route and query param in same app, the clean current rest
+ *    and update the new rest node.
+ * 3. If references same rest then update it.
+ *
+ * In addition to that, it also tracks the params unassociated to create record call if needed.
+ */
+export function getRouteAttrMapWithRestNodeResult(
+    document: Document,
+    context: Context,
+    restDocMap: any
+): Result<DocumentPointer | undefined> {
+    const restNodeId = getNodeId(getArgs(document))
+    const restNodeSysId = context.keys.explicit[restNodeId!]!.id
+    const routeId = document.data!['data']['web_service_operation']
+    if (document.action === 'DELETE') {
+        return { handled: true, result: { kind: 'record', guid: routeId } }
+    }
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    const attrName = document.data!['table'] === 'sys_ws_header_map' ? 'headers' : 'parameters'
+    if (isUnHandled) {
+        let unAssociatedId: string | undefined = undefined
+        document['changedData'] = { data: document.data!['data'] }
+        iterateAllRouteAttrNode(document, attrName, (arrayExp, element, compKey) => {
+            unAssociatedId = unAssociatedId ?? cleanMapDocInNode(arrayExp, element, compKey, context, document)
+        })
+        if (unAssociatedId) {
+            if (!isParamAssociated(document, attrName, context, unAssociatedId)) {
+                completelyUnassociatedParamIds.add(unAssociatedId)
+            }
+        }
+        deleteDocNode(document, context)
+        return { handled: false }
+    }
+    const paramField =
+        document.data!['table'] === 'sys_ws_header_map' ? 'web_service_header' : 'web_service_query_parameter'
+    potentialRecordCallRouteParams.delete(document.data!['data'][paramField])
+    const restId = getRestIdForRoute(routeId, restDocMap)!
+    if (restId !== restNodeSysId) {
+        let unAssociatedId: string | undefined = undefined
+        document['changedData'] = { data: document.data!['data'] }
+        iterateAllRouteAttrNode(document, attrName, (arrayExp, element, compKey) => {
+            unAssociatedId = unAssociatedId ?? cleanMapDocInNode(arrayExp, element, compKey, context, document)
+        })
+        if (unAssociatedId) {
+            if (!isParamAssociated(document, attrName, context, unAssociatedId)) {
+                completelyUnassociatedParamIds.add(unAssociatedId)
+            }
+        }
+        deleteDocNode(document, context)
+    }
+    return { handled: true, result: { kind: 'record', guid: routeId } }
+}
+
+/**
+ * Performs following operation
+ * 1. If given mapping record references some routes or param not in app update the record call.
+ * 2. If references some existing route and param, then remove the current record call and its keys.
+ *    Update the new rest node.
+ */
+export function getRouteAttrMapWithRecordNodeResult(
+    document: Document,
+    context: Context,
+    restDocMap: any
+): Result<DocumentPointer | undefined> {
+    if (document.action === 'DELETE') {
+        return { handled: false }
+    }
+    const routeId = document.data!['data']['web_service_operation']
+    const isUnHandled = restDocMap['unHandled_records'].find((doc) => doc.id === document.guid)
+    if (isUnHandled) {
+        return { handled: false }
+    }
+    document['changedData'] = { data: document.data!['data'] }
+    const recordId = getNodeId(getArgs(document))!
+    const paramField =
+        document.data!['table'] === 'sys_ws_header_map' ? 'web_service_header' : 'web_service_query_parameter'
+    potentialRecordCallRouteParams.delete(document.data!['data'][paramField])
+    removeNode(document.node!)
+    deleteDocNode(document, context)
+    delete context.keys.explicit[recordId]
+    return { handled: true, result: { kind: 'record', guid: routeId } }
+}
+
+/**
+ * If the incoming parameter or header record is consumed by rest associated it to the rest node, else make it a record call.
+ */
+export function getRouteAttrResult(document: Document, restDocMap: any): Result<DocumentPointer | undefined> {
+    if (document.action === 'DELETE') {
+        return { handled: false }
+    }
+    const restId = document.data!['data']['web_service_definition']
+    if (isConsumedByRest(restId, restDocMap, document)) {
+        return { handled: true, result: { kind: 'record', guid: restId } }
+    }
+    return { handled: false }
+}
+
+const findRecInDocs = (docs: any[], id: string, table: string) => {
+    return docs?.find((doc) => doc.data!['table'] === table && doc.id == id)
+}
+
+export function getRestDocumentMap(context: Context) {
+    if (restDocumentMap) {
+        return restDocumentMap
+    }
+    /**gets all rest related docs */
+    const allRestDocs = context.getAllDocuments().filter((doc) => restTables.includes(doc.data!['table']))
+    allRestDocs.sort((doc1, doc2) => {
+        const doc1Table = doc1.data!['table']
+        const doc2Table = doc2.data!['table']
+        return restTables.indexOf(doc1Table) - restTables.indexOf(doc2Table)
+    })
+    const unHandledDocs: any[] = []
+    /** filters and gets all delete records and insert_or_update records */
+    const delRestDocs = allRestDocs.filter((doc) => doc.action === 'DELETE')
+    const existingDocs = allRestDocs.filter((doc) => doc.action !== 'DELETE')
+    existingDocs.map((doc) => {
+        const table = doc.data!['table']
+        if (
+            (table === 'sys_ws_query_parameter' || table === 'sys_ws_header') &&
+            doc.node &&
+            getCallExpressionName(doc.node as ts.CallExpression) === RestApi.name
+        ) {
+            potentialRecordCallRouteParams.add(doc.guid)
+        }
+    })
+    /**
+     * Generates the rest document map with insert or udpate records
+     * and includes only mapping records that are being transformed (this is needed to determine if an
+     * parameter or header record will be consumed by rest in current transformation)
+     */
+    restDocumentMap = existingDocs.reduce((docMap, doc) => {
+        switch (doc.data!['table']) {
+            case 'sys_ws_definition':
+                docMap[doc.guid] = {
+                    restDef: doc,
+                }
+                break
+            case 'sys_ws_operation':
+                const op_restId = doc.data!['data']['web_service_definition']
+                if (docMap[op_restId]) {
+                    ;(docMap[op_restId].routes ??= {})[doc.guid] = doc
+                }
+                break
+            case 'sys_ws_version':
+                const v_restId = doc.data!['data']['web_service_definition']
+                if (docMap[v_restId]) {
+                    ;(docMap[v_restId].versions ??= {})[doc.guid] = doc
+                }
+                break
+            case 'sys_ws_query_parameter':
+            case 'sys_ws_header':
+                const qp_restId = doc.data!['data']['web_service_definition']
+                if (docMap[qp_restId]) {
+                    ;(docMap[qp_restId].route_attrs ??= {})[doc.guid] = doc
+                } else {
+                    //throw error if the transforming doc references a deleted record
+                    if (doc.changedData) {
+                        const found = findRecInDocs(delRestDocs, qp_restId, 'sys_ws_definition')
+                        if (found) {
+                            throw Error(
+                                `Found invalid rest route param record: ${doc.guid} referencing deleted rest record: ${qp_restId}`
+                            )
+                        }
+                        unHandledDocs.push(doc)
+                    }
+                }
+                break
+            case 'sys_ws_query_parameter_map':
+            case 'sys_ws_header_map':
+                if (!doc.changedData) {
+                    break
+                }
+                const attrTable =
+                    doc.data!['table'] === 'sys_ws_header_map' ? 'sys_ws_header' : 'sys_ws_query_parameter'
+                const attr =
+                    doc.data!['table'] === 'sys_ws_header_map' ? 'web_service_header' : 'web_service_query_parameter'
+                const qpm_routeId = doc.data!['data']['web_service_operation']
+                const qpm_paramId = doc.data!['data'][attr]
+                const delOperationFound = findRecInDocs(delRestDocs, qpm_routeId, 'sys_ws_operation')
+                const delParamFound = findRecInDocs(delRestDocs, qpm_paramId, attrTable)
+                if (delOperationFound || delParamFound) {
+                    throw Error(
+                        `Found invalid rest map record: ${doc.guid} referencing deleted record: ${
+                            delOperationFound ? delOperationFound : delParamFound
+                        }`
+                    )
+                }
+                const routeRec = findRecInDocs(existingDocs, qpm_routeId, 'sys_ws_operation')
+                const paramRec = findRecInDocs(existingDocs, qpm_paramId, attrTable)
+                /**if both route and parameter are part of same rest then it will be consumed by rest */
+                if (routeRec && paramRec) {
+                    const routeRestId = routeRec.data!['data']['web_service_definition']
+                    const paramRestId = paramRec.data!['data']['web_service_definition']
+                    if (routeRestId !== paramRestId) {
+                        throw Error(
+                            `Found invalid rest mapping record: ${doc.guid} which has param: ${qpm_paramId} and route: ${qpm_routeId} pointing to different rest definition`
+                        )
+                    }
+                    ;(docMap[routeRestId].route_attrs_map ??= {})[doc.guid] = doc
+                } else if (paramRec) {
+                    const paramRestId = paramRec.data!['data']['web_service_definition']
+                    const foundRestRec = findRecInDocs(existingDocs, paramRestId, 'sys_ws_definition')
+                    /**In mapping records resources and paramter should point to same rest*/
+                    if (foundRestRec) {
+                        throw Error(
+                            `Found invalid rest mapping record: ${doc.guid} where the resource references different rest entity than the rest attr.`
+                        )
+                    }
+                    unHandledDocs.push(doc)
+                } else {
+                    unHandledDocs.push(doc)
+                }
+        }
+        return docMap
+    }, {})
+    restDocumentMap['delete_records'] = delRestDocs ?? []
+    restDocumentMap['unHandled_records'] = unHandledDocs ?? []
+    return restDocumentMap
+}
+
+export function isParamAssociated(document: Document, eleAttrName: string, context: Context, paramSysId: string) {
+    let isAssociated = false
+    iterateAllRouteAttrNode(document, eleAttrName, (_expression, _element, compKey) => {
+        if (context.keys.explicit[compKey.attr]?.id === paramSysId) {
+            isAssociated = true
+        }
+    })
+    return isAssociated
+}
+
+/**
+ * Helper function that creates a record call for the document passed.
+ */
+export function createRecordCall(paramSysId: string, context: Context) {
+    const paramKey = context.keys.findExplicitKeyById(paramSysId)
+    if (paramKey) {
+        delete context.keys.explicit[paramKey]
+    }
+    const document = context.getDocument(paramSysId)!
+    document['changedData'] = { data: document.data!['data'] }
+    delete document?.node
+    const linkedDoc = RecordPlugin.generators.record(document as UnlinkedDocument<'record'> & Arranged, context)
+    RecordPlugin.transformers.record.CallExpression(linkedDoc)
+}