@servicenow/sdk-build-core 3.0.2 → 4.0.0

package/src/plugins/behaviors/extractors/Data.ts

@@ -1,332 +0,0 @@
-import { SupportedNode } from '@servicenow/sdk-project'
-
-/**
- * Actions indicate what should take place in the database when the XML file
- * is loaded. The platform understands these three actions: insert/update,
- * delete, and delete multiple.
- */
-export type Action = 'INSERT_OR_UPDATE' | 'DELETE' | 'delete_multiple'
-
-/**
- * Utility type for data passed to XML extractors for processing.
- */
-export type Xml = {
-    filePath: string
-    data: any
-}
-
-/**
- * Utility type to represent a simple object structure with primitive values.
- */
-export type PrimitiveData = {
-    [x: string]: PrimitiveData | PrimitiveData[] | string | number | boolean | undefined
-}
-
-/**
- * XML data is data from XML files (such as the parsed content of a record_update)
- * which is not associated with any AST node.
- */
-export class XmlData<D extends PrimitiveData = PrimitiveData> {
-    constructor(
-        public data: D,
-        readonly filePath: string,
-        readonly kind: string,
-        readonly action: Action = 'INSERT_OR_UPDATE'
-    ) {}
-}
-
-export type WrappedData<D> = {
-    [K in keyof D]: D[K] extends string
-        ? StringData<D[K]>
-        : D[K] extends number
-          ? NumberData<D[K]>
-          : D[K] extends boolean
-            ? BooleanData<D[K]>
-            : D[K] extends Array<unknown>
-              ? ArrayData<D[K]>
-              : D[K] extends Record<string, unknown>
-                ? ObjectData<D[K]>
-                : Data<D[K]>
-}
-
-export type TypeName = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'entity'
-export type Type<T extends TypeName> = T extends 'string'
-    ? StringData
-    : T extends 'number'
-      ? NumberData
-      : T extends 'boolean'
-        ? BooleanData
-        : T extends 'array'
-          ? ArrayData
-          : T extends 'object'
-            ? ObjectData
-            : T extends 'entity'
-              ? EntityData
-              : never
-
-function getClassFromTypeName(type: TypeName) {
-    switch (type) {
-        case 'string':
-            return StringData
-        case 'number':
-            return NumberData
-        case 'boolean':
-            return BooleanData
-        case 'array':
-            return ArrayData
-        case 'object':
-            return ObjectData
-        case 'entity':
-            return EntityData
-        default:
-            throw new Error(`Unrecognized type name: ${type}`)
-    }
-}
-
-export abstract class Data<D = unknown> {
-    constructor(private readonly node: SupportedNode) {}
-
-    /**
-     * @deprecated Using this for an array or object is bad practice because all of the elements/properties
-     * will be assigned the same node as the array/object itself. This makes it difficult to bidrectionally
-     * sync data created this way because you don't have the granularity required to know where each of the
-     * element/property values (and any nested values) came from.
-     */
-    static fromValue<const D>(value: D, node: SupportedNode): Data<D> {
-        if (value === undefined || value === null) {
-            return new UndefinedData(node) as Data<D> // TODO: How can we avoid this silly cast?
-        } else if (typeof value === 'string') {
-            return new StringData(value, node)
-        } else if (typeof value === 'number') {
-            return new NumberData(value, node)
-        } else if (typeof value === 'boolean') {
-            return new BooleanData(value, node)
-        } else if (Array.isArray(value)) {
-            return ArrayData.fromArrayValue(value, node)
-        } else if (!!value && typeof value === 'object') {
-            const obj = Object.fromEntries(Object.entries(value).filter(([key]) => typeof key === 'string'))
-            return ObjectData.fromObjectValue(obj as typeof obj & D, node)
-        } else {
-            throw new Error(
-                `Unsupported data type: ${value} (Type: ${typeof value}, Class: ${value?.constructor?.name})`
-            )
-        }
-    }
-
-    static isUndefined(data?: unknown): data is UndefinedData {
-        return data instanceof UndefinedData
-    }
-
-    static isString(data?: unknown): data is StringData {
-        return data instanceof StringData
-    }
-
-    static isNumber(data?: unknown): data is NumberData {
-        return data instanceof NumberData
-    }
-
-    static isBoolean(data?: unknown): data is BooleanData {
-        return data instanceof BooleanData
-    }
-
-    static isArray(data?: unknown): data is ArrayData {
-        return data instanceof ArrayData
-    }
-
-    static isObject(data?: unknown): data is ObjectData {
-        return data instanceof ObjectData
-    }
-
-    static isEntity(data?: unknown): data is EntityData {
-        return data instanceof EntityData
-    }
-
-    abstract getValue(resolveReferences?: boolean): D
-
-    getNode(): SupportedNode {
-        return this.node
-    }
-
-    needsCDATATag(): boolean {
-        return false
-    }
-}
-
-export class UndefinedData extends Data<undefined> {
-    constructor(node: SupportedNode) {
-        super(node)
-    }
-
-    getValue() {
-        return undefined
-    }
-}
-
-export class StringData<const D extends string = string> extends Data<D> {
-    constructor(
-        private readonly value: D,
-        node: SupportedNode,
-        private options: {
-            needsCDATA: boolean
-        } = { needsCDATA: false }
-    ) {
-        super(node)
-    }
-
-    getValue() {
-        return this.value
-    }
-
-    override needsCDATATag() {
-        return this.options.needsCDATA
-    }
-}
-
-export class NumberData<const D extends number = number> extends Data<D> {
-    constructor(
-        private readonly value: D,
-        node: SupportedNode
-    ) {
-        super(node)
-    }
-
-    getValue() {
-        return this.value
-    }
-}
-
-export class BooleanData<const D extends boolean = boolean> extends Data<D> {
-    constructor(
-        private readonly value: D,
-        node: SupportedNode
-    ) {
-        super(node)
-    }
-
-    getValue() {
-        return this.value
-    }
-}
-
-export class ArrayData<const D extends unknown[] = unknown[]> extends Data<D> {
-    constructor(
-        private readonly elements: WrappedData<D>,
-        node: SupportedNode
-    ) {
-        super(node)
-    }
-
-    /**
-     * @deprecated Using this for arrays is bad practice because all of the array elements will be
-     * assigned the same node as the array itself. This makes it difficult to bidrectionally sync
-     * data created this way because you don't have the granularity required to know where each of
-     * the element values (and any nested values) came from.
-     */
-    static fromArrayValue<const D extends unknown[]>(value: D, node: SupportedNode): ArrayData<D> {
-        const elements = value.map((value) => Data.fromValue(value, node)) as WrappedData<D>
-
-        return new ArrayData(elements, node)
-    }
-
-    getValue(resolveReferences = false) {
-        return this.elements.map((element) =>
-            !resolveReferences && Data.isEntity(element) ? element.getGuid() : element.getValue()
-        ) as D
-    }
-
-    getElements() {
-        return this.elements
-    }
-}
-
-export class ObjectData<const D extends Record<string, unknown> = Record<string, unknown>> extends Data<D> {
-    constructor(
-        private readonly properties: WrappedData<D>,
-        node: SupportedNode
-    ) {
-        super(node)
-    }
-
-    /**
-     * @deprecated Using this for objects is bad practice because all of the object properties will
-     * be assigned the same node as the object itself. This makes it difficult to bidrectionally sync
-     * data created this way because you don't have the granularity required to know where each of
-     * the property values (and any nested values) came from.
-     */
-    static fromObjectValue<const D extends Record<string, unknown>>(value: D, node: SupportedNode): ObjectData<D> {
-        const properties = Object.fromEntries(
-            Object.entries(value).map(([key, value]) => [key, Data.fromValue(value, node)])
-        ) as WrappedData<D>
-
-        return new ObjectData(properties, node)
-    }
-
-    getValue(resolveReferences = false) {
-        return Object.fromEntries(
-            Object.entries(this.properties).map(([key, value]) => [
-                key,
-                !resolveReferences && Data.isEntity(value) ? value.getGuid() : value.getValue(),
-            ])
-        ) as D
-    }
-
-    getProperty<const K extends keyof D, const T extends TypeName>(
-        name: K,
-        type?: T
-    ): TypeName extends T ? WrappedData<D>[K] : Type<T> | undefined {
-        const property = this.properties[name]
-        if (type) {
-            const expectedClass = getClassFromTypeName(type)
-            if (!(property instanceof expectedClass)) {
-                return undefined as any
-            }
-        }
-
-        return property as any
-    }
-
-    getPropertyOrThrow<const K extends keyof D, const T extends TypeName>(
-        name: K,
-        type?: T
-    ): TypeName extends T ? NonNullable<WrappedData<D>[K]> : Type<T> {
-        const property = this.getProperty(name, type)
-        if (!property) {
-            throw new Error(`Property "${name.toString()}" not found on object`)
-        }
-
-        return property as any
-    }
-
-    getProperties() {
-        return this.properties
-    }
-}
-
-export class EntityData<const D extends Record<string, unknown> = Record<string, unknown>> extends ObjectData<D> {
-    constructor(
-        private readonly kind: string,
-        private readonly guid: string,
-        entity: ObjectData<D>,
-        node: SupportedNode,
-        private installMethod?: string,
-        private explicitIds?: string[]
-    ) {
-        super(entity.getProperties(), node)
-    }
-
-    getInstallMethod() {
-        return this.installMethod
-    }
-
-    getKind() {
-        return this.kind
-    }
-
-    getGuid() {
-        return this.guid
-    }
-
-    getExplicitIds() {
-        return this.explicitIds ?? []
-    }
-}

package/src/plugins/behaviors/extractors/Extractors.ts

@@ -1,73 +0,0 @@
-import { SupportedKindName, SupportedNodeByKindName } from '@servicenow/sdk-project'
-import { Data, EntityData, Xml, XmlData } from './Data'
-import { Context } from '../../Context'
-import { FluentDiagnostic } from '../../Diagnostic'
-
-export type ExtractionResult<D extends Data = Data> =
-    | {
-          handled: false
-      }
-    | {
-          handled: true
-          data?: D | undefined
-          diagnostics: FluentDiagnostic[]
-      }
-
-/**
- * An XML extractor function accepts an {@linkcode Xml} object and returns one or
- * more pieces of {@linkcode XmlData} extracted from that object. The function may
- * also return undefined to indicate that it did not handle the object.
- */
-export type XmlExtractorFunction = (xml: Xml, context: Context) => XmlData | XmlData[] | undefined
-
-/**
- * A raw extractor function accepts an AST node and returns one or more pieces of
- * {@linkcode Data} extracted from that node which cannot be composed into documents
- * on their own but could be part of an entity.
- */
-export type RawExtractorFunction<N extends SupportedKindName | 'any' = SupportedKindName> = (
-    node: N extends SupportedKindName ? SupportedNodeByKindName<N> : any,
-    context: Context
-) => ExtractionResult<Data>
-
-/**
- * An entity extractor function accepts an AST node and returns one or more pieces
- * of {@linkcode EntityData} extracted from that node which can then be composed
- * into documents.
- */
-export type EntityExtractorFunction<N extends SupportedKindName | 'any' = SupportedKindName> = (
-    node: N extends SupportedKindName ? SupportedNodeByKindName<N> : any,
-    context: Context
-) => ExtractionResult<EntityData>
-
-// This is only imported so it can be referenced in the JS doc below
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-import type { Plugin } from '../../Plugin'
-
-/**
- * @see {@linkcode Plugin#extractors}
- */
-export type Extractors<
-    FluentRawNodeKinds extends SupportedKindName | 'any',
-    ModuleRawNodeKinds extends SupportedKindName | 'any',
-    JsonRawNodeKinds extends SupportedKindName | 'any',
-    AnyRawNodeKinds extends SupportedKindName | 'any',
-    FluentEntityNodeKinds extends SupportedKindName | 'any',
-    ModuleEntityNodeKinds extends SupportedKindName | 'any',
-    JsonEntityNodeKinds extends SupportedKindName | 'any',
-    AnyEntityNodeKinds extends SupportedKindName | 'any',
-> = {
-    xml?: XmlExtractorFunction
-    raw?: {
-        fluent?: { [K in FluentRawNodeKinds]: RawExtractorFunction<K> }
-        module?: { [K in ModuleRawNodeKinds]: RawExtractorFunction<K> }
-        json?: { [K in JsonRawNodeKinds]: RawExtractorFunction<K> }
-        any?: { [K in AnyRawNodeKinds]: RawExtractorFunction<K> }
-    }
-    entity?: {
-        fluent?: { [K in FluentEntityNodeKinds]: EntityExtractorFunction<K> }
-        module?: { [K in ModuleEntityNodeKinds]: EntityExtractorFunction<K> }
-        json?: { [K in JsonEntityNodeKinds]: EntityExtractorFunction<K> }
-        any?: { [K in AnyEntityNodeKinds]: EntityExtractorFunction<K> }
-    }
-}

package/src/plugins/behaviors/extractors/index.ts

@@ -1,2 +0,0 @@
-export * from './Extractors'
-export * from './Data'

package/src/plugins/behaviors/index.ts

@@ -1,9 +0,0 @@
-export * from './extractors'
-export * from './Composer'
-export * from './Arranger'
-export * from './Serializer'
-export * from './Generator'
-export * from './Transformer'
-export * from './PostProcessor'
-export * from './Diagnostics'
-export * from './OwnedTables'

package/src/plugins/util/CallExpression.ts

@@ -1,110 +0,0 @@
-import { ts } from '@servicenow/sdk-project'
-import { Context } from '../Context'
-import { EntityData, ExtractionResult, ObjectData } from '../behaviors'
-import { FluentDiagnostic } from '../Diagnostic'
-
-export function getCallExpressionName(node: ts.CallExpression) {
-    const expression = node.getExpression()
-    if (ts.Node.isIdentifier(expression)) {
-        return expression.getText()
-    } else if (ts.Node.isPropertyAccessExpression(expression)) {
-        return expression.getName()
-    } else {
-        throw `CallExpression does not have an identifier: ${expression.getText()}`
-    }
-}
-
-export function extractCallExpression<
-    const A extends unknown[],
-    const E extends A extends [infer T extends Record<string, unknown>] ? T : never,
-    const K extends string,
->(
-    fn: (...args: A) => E,
-    kind: K,
-    node: ts.CallExpression,
-    context: Context,
-    guid: (entity: E) => string,
-    validate: (entity: unknown) => entity is E = (_): _ is E => true
-): ExtractionResult<EntityData<E>> {
-    let name = ''
-    try {
-        name = getCallExpressionName(node)
-    } catch (e) {
-        return {
-            handled: true,
-            diagnostics: [new FluentDiagnostic(node, 'Unsupported call expression')],
-        }
-    }
-
-    if (name !== fn.name) {
-        return { handled: false }
-    }
-
-    const diagnostics: FluentDiagnostic[] = []
-    const args = node
-        .getArguments()
-        .map((a) => {
-            const result = context.extractAst(a)
-            if (!result.handled) {
-                diagnostics.push(new FluentDiagnostic(a, `Unsupported argument in ${fn.name} call`))
-                return undefined
-            }
-
-            diagnostics.push(...result.diagnostics)
-            if (!result.data) {
-                diagnostics.push(new FluentDiagnostic(a, `Unsupported argument in ${fn.name} call`))
-                return undefined
-            }
-
-            return result.data
-        })
-        .filter((a) => a !== undefined)
-
-    if (!(0 in args) || args.length !== 1) {
-        return {
-            handled: true,
-            diagnostics: [
-                ...diagnostics,
-                new FluentDiagnostic(node, `Expected ${fn.name} call to have exactly one argument`),
-            ],
-        }
-    }
-
-    const entity = args[0] as ObjectData<E>
-    const entityValue = entity.getValue()
-    if (!validate(entityValue)) {
-        return {
-            handled: true,
-            diagnostics: [...diagnostics, new FluentDiagnostic(node, `Invalid ${fn.name} call argument`)],
-        }
-    }
-
-    return {
-        handled: true,
-        diagnostics,
-        data: new EntityData(
-            kind,
-            guid(entityValue),
-            entity,
-            node,
-            extractInstallMethod(entity),
-            extractExplicitId(entity)
-        ),
-    }
-}
-
-function extractInstallMethod<const D extends Record<string, unknown>>(entity: ObjectData<D>) {
-    const $meta = entity.getProperty('$meta')
-    if (!$meta) {
-        return
-    }
-    return $meta.getValue()['installMethod']
-}
-
-function extractExplicitId<const D extends Record<string, unknown>>(entity: ObjectData<D>) {
-    const $id = entity.getProperty('$id')
-    if (!$id) {
-        return []
-    }
-    return [`${$id.getValue()}`]
-}