@servicenow/sdk-build-core 3.0.2 → 4.0.0

package/src/keys-registry.ts

@@ -0,0 +1,384 @@
+import { path } from './path'
+import { ts, parseType } from './typescript'
+import type { App } from './app'
+import type { Compiler } from './compiler'
+import { GUID, isGUID } from './guid'
+import * as z from 'zod'
+import type { CoalesceKeys } from './plugins'
+import { JSON5 } from './json'
+import { Formatter } from './formatter'
+import type { FileSystem } from './fs'
+
+export const KEYS_MODULE = '@servicenow/sdk/global'
+export const KEYS_FILE_NAME = 'keys.ts'
+
+const NestedCoalesceKeysSchema: z.ZodType<Now.Internal.KeysRegistry['composite'][number]['key']> = z.lazy(() =>
+    z.record(
+        z.string().or(
+            z.object({
+                id: z.string(),
+                key: NestedCoalesceKeysSchema,
+            })
+        )
+    )
+)
+
+const CompositeKeySchema = z.object({
+    table: z.string(),
+    id: z.string(),
+    deleted: z.boolean().optional(),
+    key: NestedCoalesceKeysSchema,
+})
+
+const KeysSchema = z.object({
+    explicit: z
+        .record(
+            z.string().or(z.number()),
+            z.object({
+                table: z.string(),
+                id: z.string(),
+                deleted: z.boolean().optional(),
+            })
+        )
+        .default({}),
+    composite: z.array(CompositeKeySchema).default([]),
+    deleted: z.record(z.string(), z.array(z.string())).default({}),
+})
+
+export class KeysRegistry {
+    private readonly formatter: Formatter
+    private readonly file: ts.SourceFile
+    private readonly usedIds: Set<string> = new Set()
+    private registry: Now.Internal.KeysRegistry
+
+    constructor(compiler: Compiler, project: App, fs: FileSystem) {
+        this.formatter = new Formatter(fs)
+        const keysFilePath = path.resolve(project.rootDir, project.config.generatedDir, KEYS_FILE_NAME)
+        const existingFile = compiler.addSourceFileAtPathIfExists(keysFilePath)
+
+        if (existingFile) {
+            this.registry = KeysRegistry.parseKeysFile(existingFile)
+            this.file = existingFile
+        } else {
+            this.registry = KeysSchema.parse({})
+            this.file = compiler.createSourceFile(keysFilePath, KeysRegistry.getCode({}), {
+                overwrite: true,
+                scriptKind: ts.ScriptKind.TS,
+            })
+        }
+    }
+
+    static parseKeysFile(keysFile: ts.SourceFile): Now.Internal.KeysRegistry {
+        const keysInterface = KeysRegistry.getKeysInterface(keysFile)
+        const parsedType = parseType(keysInterface.getType(), keysInterface, (unparsableType) => {
+            if (unparsableType.isArray()) {
+                return [] // If the keys file doesn't have composite keys, it will be an unparsable array so just return an empty one
+            } else {
+                throw `Unparsable type in keys.ts: ${unparsableType.getText()}`
+            }
+        })
+
+        const result = KeysSchema.safeParse(parsedType)
+        if (!result.success) {
+            throw new Error(`Keys registry is malformed: ${JSON5.stringify(result.error.format(), { space: 4 })}`)
+        }
+
+        return result.data
+    }
+
+    private static getKeysInterface(keysFile: ts.SourceFile) {
+        return keysFile
+            .getModuleOrThrow('global')
+            .getModuleOrThrow('Now')
+            .getModuleOrThrow('Internal')
+            .getInterfaceOrThrow('Keys')
+    }
+
+    private use<const K extends Now.Internal.ExplicitKey | Now.Internal.CompositeKey>(key: K): K {
+        if (key.deleted) {
+            key.deleted = false // If it was previously registered as deleted, reverse it
+        }
+
+        this.usedIds.add(key.id)
+        return key
+    }
+
+    getSourceFile(): ts.SourceFile {
+        return this.file
+    }
+
+    private queryExplicitKey(table: string, key: string | number): Now.Internal.ExplicitKey | undefined {
+        const existing = this.registry.explicit[key]
+        return existing?.table === table ? existing : undefined
+    }
+
+    queryExplicitId(table: string, key: string | number): string | undefined {
+        return this.queryExplicitKey(table, key)?.id
+    }
+
+    private registerExplicitKey(table: string, key: string | number, guidOverride?: string): Now.Internal.ExplicitKey {
+        const existing = this.queryExplicitKey(table, key)
+        if (existing) {
+            return this.use(existing)
+        }
+
+        let id: string
+        if (guidOverride) {
+            id = guidOverride
+        } else if (typeof key === 'string' && isGUID(key)) {
+            id = key
+        } else {
+            id = GUID()
+        }
+
+        const newKey = { table, id }
+        this.registry.explicit[key] = newKey
+        return this.use(newKey)
+    }
+
+    registerExplicitId(table: string, key: string | number, guidOverride?: string): string {
+        return this.registerExplicitKey(table, key, guidOverride).id
+    }
+
+    private deleteExplicitKey(table: string, key: string | number, guidOverride?: string): Now.Internal.ExplicitKey {
+        const registeredKey = this.registerExplicitKey(table, key, guidOverride)
+        registeredKey.deleted = true
+        return registeredKey
+    }
+
+    deleteExplicitId(table: string, key: string | number, guidOverride?: string): string {
+        return this.deleteExplicitKey(table, key, guidOverride).id
+    }
+
+    private queryCompositeKey(
+        table: string,
+        query: CoalesceKeys,
+        guid?: string
+    ): Now.Internal.CompositeKey | undefined {
+        const serializedQuery = this.serializeCoalesceKeys(query)
+        return this.registry.composite.find(
+            (existing) =>
+                existing.table === table &&
+                (existing.id === guid || this.coalesceKeysAreEqual(existing.key, serializedQuery, table))
+        )
+    }
+
+    queryCompositeId(table: string, query: CoalesceKeys): string | undefined {
+        return this.queryCompositeKey(table, query)?.id
+    }
+
+    private registerCompositeKey(table: string, key: CoalesceKeys, guidOverride?: string): Now.Internal.CompositeKey {
+        const existing = this.queryCompositeKey(table, key, guidOverride)
+        if (existing) {
+            return this.use(existing)
+        }
+
+        const newKey = {
+            table,
+            id: guidOverride ?? GUID(),
+            key: this.serializeCoalesceKeys(key),
+        }
+
+        const registry = (this.registry.composite ??= [])
+        registry.push(newKey)
+        return this.use(newKey)
+    }
+
+    registerCompositeId(table: string, key: CoalesceKeys, guidOverride?: string): string {
+        return this.registerCompositeKey(table, key, guidOverride).id
+    }
+
+    private deleteCompositeKey(table: string, key: CoalesceKeys, guidOverride?: string): Now.Internal.CompositeKey {
+        const registeredKey = this.registerCompositeKey(table, key, guidOverride)
+        registeredKey.deleted = true
+        return registeredKey
+    }
+
+    deleteCompositeId(table: string, key: CoalesceKeys, guidOverride?: string): string {
+        return this.deleteCompositeKey(table, key, guidOverride).id
+    }
+
+    private serializeCoalesceKeys(keys: CoalesceKeys): Now.Internal.KeysRegistry['composite'][number]['key'] {
+        if (Object.keys(keys).length <= 0) {
+            throw new Error('Coalesce keys object is empty.')
+        }
+
+        return Object.fromEntries(
+            Object.entries(keys).map(([k, v]) => {
+                if (!v) {
+                    return [k, 'NULL'] // Nullish or empty values should be represented as "NULL" to be consistent with how the platform handles coalesce strategies
+                } else if (typeof v === 'string') {
+                    return [k, v]
+                } else {
+                    const nestedKeys = v.getKeys()
+                    if (nestedKeys) {
+                        return [k, { id: v.getValue(), key: this.serializeCoalesceKeys(nestedKeys) }]
+                    } else {
+                        return [k, v.getValue()]
+                    }
+                }
+            })
+        )
+    }
+
+    /**
+     * Checks if the coalesce keys from `left` are equal to those specified in `right`. If there
+     * are keys in `left` that aren't present in `right`, they are ignored. However, if there are
+     * keys in `right` that aren't present in `left`, the two are considered NOT equal.
+     *
+     * If any nested coalesce keys are present on either side, they are considered equal when any
+     * ONE of the following conditions are met:
+     *
+     * A) One of the values is a string that matches the nested key's ID
+     *
+     *     { id: '123', key: { k: 'v' } } == '123' }
+     *
+     * B) Both values are nested keys with matching IDs
+     *
+     *     { id: '123', key: { k: 'v' } } == { id: '123', key: { ... } }
+     *
+     * C) Both values are nested keys with matching coalesce values
+     *
+     *     { id: '123', key: { k: 'v' } } == { id: '456', key: { k: 'v' } }
+     *
+     * For condition C, the nested keys are compared recursively, so if they contain any of their
+     * own nested keys, they will be compared in the same way.
+     */
+    private coalesceKeysAreEqual(
+        leftOrig: Now.Internal.KeysRegistry['composite'][number]['key'],
+        rightOrig: Now.Internal.KeysRegistry['composite'][number]['key'],
+        table?: string
+    ): boolean {
+        const left = table ? this.mapLegacyKeys(leftOrig, table) : leftOrig
+        const right = table ? this.mapLegacyKeys(rightOrig, table) : rightOrig
+        for (const [k, rightValue] of Object.entries(right)) {
+            const match = () => {
+                const leftValue = left[k]
+                switch (typeof leftValue) {
+                    case 'string': {
+                        // Left is a plain value or ID
+                        const newLeft = this.queryExplicitId(k, leftValue) ?? leftValue // query if we have a legacy explicit ID and use that sys_Id if found
+                        return typeof rightValue === 'string'
+                            ? newLeft === rightValue // Right is the same plain value or ID
+                            : newLeft === rightValue.id // Right is a nested key with the same ID
+                    }
+                    case 'object': // Left is a nested key
+                        return typeof rightValue === 'string'
+                            ? leftValue.id === rightValue // Right is the same ID
+                            : leftValue.id === rightValue.id || // Right is a nested key with the same ID
+                                  this.coalesceKeysAreEqual(leftValue.key, rightValue.key) // Right is a nested key with matching coalesce values
+                    default:
+                        return false
+                }
+            }
+
+            if (!match()) {
+                return false // Give up as soon as we find any mismatch
+            }
+        }
+
+        return true // All keys matched
+    }
+
+    mapLegacyKeys(obj: NonNullable<object>, table?: string) {
+        // Copy to avoid messing up future iterations
+        const newObj = Object.assign({}, obj)
+
+        // Map old and new values to the table name in case we need to query explicit IDs
+        const legacyKeyMap = {
+            list: 'sys_ui_list',
+            list_id: 'sys_ui_list',
+            route: 'sys_ws_operation',
+            web_service_operation: 'sys_ws_operation',
+            web_service_header: 'sys_ws_header',
+            attr: table === 'sys_ws_query_parameter_map' ? 'sys_ws_query_parameter' : 'sys_ws_header', // attr maps to a different table depending on the type of record
+            web_service_query_parameter: 'sys_ws_query_parameter',
+        }
+
+        // Legacy key equivalence for comparison
+        Object.entries(newObj).forEach(([key, value]) => {
+            if (legacyKeyMap[key]) {
+                newObj[legacyKeyMap[key]] = value
+                delete newObj[key]
+            }
+        })
+        if (newObj['rest']) {
+            delete newObj['rest']
+        }
+        return newObj
+    }
+
+    getEffectiveExplicitKeys(): Now.Internal.KeysRegistry['explicit'] {
+        return Object.fromEntries(
+            Object.entries(this.registry.explicit)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .filter(([, v]) => !this.registry.composite.some((k) => k.table === v.table && k.id === v.id)) // Filter out any explicit IDs that became coalescing IDs later
+                .map(([k, v]) => [k, this.usedIds.has(v.id) ? v : { ...v, deleted: true }])
+        )
+    }
+
+    getEffectiveCompositeKeys(): Now.Internal.KeysRegistry['composite'] {
+        return this.registry.composite
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((v) =>
+                this.usedIds.has(v.id)
+                    ? 'deleted' in v
+                        ? // Seems silly but this is to make sure the position of the "delete" prop is consistent
+                          { table: v.table, id: v.id, deleted: v.deleted, key: v.key }
+                        : v
+                    : { table: v.table, id: v.id, deleted: true, key: v.key }
+            )
+    }
+
+    getEffectiveDeletedKeys(): Now.Internal.AnyKey[] {
+        const explicit = Object.values(this.getEffectiveExplicitKeys()).filter((k) => k.deleted)
+        const composite = this.getEffectiveCompositeKeys().filter((k) => k.deleted)
+        const deleted = Object.entries(this.registry.deleted).flatMap(([table, keys]) =>
+            keys.map((id) => ({ table, id }))
+        )
+
+        return [...explicit, ...composite, ...deleted].sort((a, b) => a.id.localeCompare(b.id))
+    }
+
+    async commit(formatter: Formatter = this.formatter): Promise<void> {
+        const explicit = this.getEffectiveExplicitKeys()
+        const composite = this.getEffectiveCompositeKeys()
+        const deleted = this.registry.deleted
+
+        const registry: Partial<Now.Internal.KeysRegistry> = {
+            ...(Object.keys(explicit).length > 0 ? { explicit } : {}),
+            ...(composite.length > 0 ? { composite } : {}),
+            ...(Object.keys(deleted).length > 0 ? { deleted } : {}),
+        }
+
+        const formatted = await formatter.format(KeysRegistry.getCode(registry), this.file.getFilePath())
+        this.file.replaceText([this.file.getPos(), this.file.getEnd()], formatted)
+        this.registry = KeysRegistry.parseKeysFile(this.file)
+    }
+
+    private static getCode(registry: Partial<Now.Internal.KeysRegistry>): string {
+        return `import '${KEYS_MODULE}'
+
+declare global {
+    namespace Now {
+        namespace Internal {
+            interface Keys extends KeysRegistry ${JSON5.stringify(registry, { space: 4 })}
+        }
+    }
+}
+`
+    }
+
+    reload(): void {
+        this.registry = KeysRegistry.parseKeysFile(this.file)
+        this.usedIds.clear()
+    }
+
+    getValue(): Now.Internal.KeysRegistry {
+        return {
+            explicit: this.registry.explicit,
+            composite: this.registry.composite,
+            deleted: this.registry.deleted,
+        }
+    }
+}

package/src/logger.ts

@@ -0,0 +1,20 @@
+export type Logger = {
+    info: (...data: any[]) => void
+    warn: (...data: any[]) => void
+    error: (...data: any[]) => void
+    debug: (...data: any[]) => void
+}
+
+// TODO: This is not needed, get rid of it
+export function createConsoleLogger(): Logger {
+    return console
+}
+
+export function createSilentLogger(): Logger {
+    return {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+    }
+}