@servicenow/sdk-build-core 3.0.2 → 4.0.0

package/src/plugins/shape.ts

@@ -0,0 +1,1532 @@
+import { type Source, Product } from './product'
+import { path } from '../path'
+import { ts } from '../typescript'
+import type { Plugin } from './plugin'
+import type { InstallCategory } from './file'
+import { JSON5 } from '../json'
+import * as _ from 'lodash'
+
+// biome-ignore lint/suspicious/noExplicitAny: TypeScript is annoying about function arguments. There's not any better options here.
+export type ShapeClass<P extends Shape = Shape> = (abstract new (...args: any[]) => P) & { prototype: P }
+
+export abstract class Shape<T = unknown> extends Product {
+    constructor({ source }: { source: Source }) {
+        super(source)
+    }
+
+    /**
+     * Instantiate an appropriate shape from the given value. If the value is already
+     * a shape, it will be returned as-is.
+     */
+    static from(source: Source, value: unknown): Shape {
+        if (value instanceof Shape) {
+            return value
+        } else if (typeof value === 'string') {
+            return new StringLiteralShape({ source, literalText: value })
+        } else if (typeof value === 'number') {
+            return new NumberShape({ source, value })
+        } else if (typeof value === 'boolean') {
+            return new BooleanShape({ source, value })
+        } else if (value === undefined || value === null) {
+            return new UndefinedShape({ source })
+        } else if (Array.isArray(value)) {
+            return new ArrayShape({ source, elements: value })
+        } else if (typeof value === 'object') {
+            return new ObjectShape({ source, properties: value })
+        } else {
+            throw new Error(
+                `Tried to create shape from invalid value (type: ${typeof value}): ${JSON5.stringify(value)}`
+            )
+        }
+    }
+
+    /**
+     * Instantiate a NoOpShape which has no value and will not generate or update
+     * any code. Useful for shapes that are not supported for bidirectional sync.
+     */
+    static noOp(source: Source): NoOpShape {
+        return new NoOpShape(source)
+    }
+
+    /**
+     * Gets the value of the shape.
+     */
+    getValue(): T {
+        return Symbol(this.getKind()) as T
+    }
+
+    equals(value: unknown): boolean {
+        value = value instanceof Shape ? value.getValue() : value
+        return value === this.getValue()
+    }
+
+    pipe<T>(pipeFn: (shape: this) => T): T {
+        return pipeFn(this)
+    }
+
+    isResolvable(): this is ResolvableShape {
+        return this.is(ResolvableShape)
+    }
+
+    isIdentifier(): this is IdentifierShape {
+        return this.is(IdentifierShape)
+    }
+
+    isString(): this is StringShape {
+        return this.is(StringShape)
+    }
+
+    isStringLiteral(): this is StringLiteralShape {
+        return this.is(StringLiteralShape)
+    }
+
+    isNumber(): this is NumberShape {
+        return this.is(NumberShape)
+    }
+
+    isBoolean(): this is BooleanShape {
+        return this.is(BooleanShape)
+    }
+
+    isNoOp(): this is NoOpShape {
+        return this.is(NoOpShape)
+    }
+
+    isUnresolved(): this is UnresolvedShape {
+        return this.is(UnresolvedShape)
+    }
+
+    isUndefined(): this is UndefinedShape {
+        return this.is(UndefinedShape)
+    }
+
+    isDefined(): this is this {
+        return !this.isUndefined() && !this.isUnresolved() && !this.isNoOp()
+    }
+
+    isArray(): this is ArrayShape {
+        return this.is(ArrayShape)
+    }
+
+    isObject(): this is ObjectShape {
+        return this.is(ObjectShape)
+    }
+
+    isRecord(): this is Record {
+        return this.is(Record)
+    }
+
+    isRecordId(): this is RecordId {
+        return this.is(RecordId)
+    }
+
+    is<const T extends [Shape, Shape, ...Shape[]]>(
+        shapeClasses: { [I in keyof T]: ShapeClass<T[I]> },
+        failureMessage?: string
+    ): this is T[number]
+    is<const S extends Shape>(shapeClass: ShapeClass<S>, failureMessage?: string): this is S
+    is(shapeClass: ShapeClass | ShapeClass[]): boolean {
+        for (const c of Array.isArray(shapeClass) ? shapeClass : [shapeClass]) {
+            if (this instanceof c) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    ifResolvable(): ResolvableShape | undefined {
+        return this.if(ResolvableShape)
+    }
+
+    ifIdentifier(): IdentifierShape | undefined {
+        return this.if(IdentifierShape)
+    }
+
+    ifString(): StringShape | undefined {
+        return this.if(StringShape)
+    }
+
+    ifStringLiteral(): StringLiteralShape | undefined {
+        return this.if(StringLiteralShape)
+    }
+
+    ifNumber(): NumberShape | undefined {
+        return this.if(NumberShape)
+    }
+
+    ifBoolean(): BooleanShape | undefined {
+        return this.if(BooleanShape)
+    }
+
+    ifUnresolved(): UnresolvedShape | undefined {
+        return this.if(UnresolvedShape)
+    }
+
+    ifUndefined(): UndefinedShape | undefined {
+        return this.if(UndefinedShape)
+    }
+
+    ifDefined(): this | undefined {
+        return this.isDefined() ? this : undefined
+    }
+
+    ifArray(): ArrayShape | undefined {
+        return this.if(ArrayShape)
+    }
+
+    ifObject(): ObjectShape | undefined {
+        return this.if(ObjectShape)
+    }
+
+    ifRecord(): Record | undefined {
+        return this.if(Record)
+    }
+
+    ifRecordId(): RecordId | undefined {
+        return this.if(RecordId)
+    }
+
+    if<const T extends [Shape, Shape, ...Shape[]]>(
+        shapeClasses: { [I in keyof T]: ShapeClass<T[I]> },
+        failureMessage?: string
+    ): T[number] | undefined
+    if<const S extends Shape>(shapeClass: ShapeClass<S>, failureMessage?: string): S | undefined
+    if(shapeClass: ShapeClass | ShapeClass[]): Shape | undefined {
+        return this.is(shapeClass as any) ? this : undefined
+    }
+
+    asResolvable(failureMessage?: string): ResolvableShape {
+        return this.as(ResolvableShape, failureMessage)
+    }
+
+    asIdentifier(failureMessage?: string): IdentifierShape {
+        return this.as(IdentifierShape, failureMessage)
+    }
+
+    asString(failureMessage?: string): StringShape {
+        return this.as(StringShape, failureMessage)
+    }
+
+    asStringLiteral(failureMessage?: string): StringLiteralShape {
+        return this.as(StringLiteralShape, failureMessage)
+    }
+
+    asNumber(failureMessage?: string): NumberShape {
+        return this.as(NumberShape, failureMessage)
+    }
+
+    asBoolean(failureMessage?: string): BooleanShape {
+        return this.as(BooleanShape, failureMessage)
+    }
+
+    asUnresolved(failureMessage?: string): UnresolvedShape {
+        return this.as(UnresolvedShape, failureMessage)
+    }
+
+    asUndefined(failureMessage?: string): UndefinedShape {
+        return this.as(UndefinedShape, failureMessage)
+    }
+
+    asArray(failureMessage?: string): ArrayShape {
+        return this.as(ArrayShape, failureMessage)
+    }
+
+    asObject(failureMessage?: string): ObjectShape {
+        return this.as(ObjectShape, failureMessage)
+    }
+
+    asRecord(failureMessage?: string): Record {
+        return this.as(Record, failureMessage)
+    }
+
+    asRecordId(failureMessage?: string): RecordId {
+        return this.as(RecordId, failureMessage)
+    }
+
+    as<const T extends [Shape, Shape, ...Shape[]]>(
+        shapeClasses: { [I in keyof T]: ShapeClass<T[I]> },
+        failureMessage?: string
+    ): T[number]
+    as<const S extends Shape>(shapeClass: ShapeClass<S>, failureMessage?: string): S
+    as(shapeClass: ShapeClass | ShapeClass[], failureMessage?: string): Shape {
+        for (const c of Array.isArray(shapeClass) ? shapeClass : [shapeClass]) {
+            if (this.is(c)) {
+                return this
+            }
+        }
+
+        throw new Error(
+            failureMessage ??
+                `Failed to cast ${this.getKind()} to ${Array.isArray(shapeClass) ? `any of the requested shapes: ${shapeClass.map((c) => c.name).join(', ')}` : shapeClass.name}`
+        )
+    }
+
+    override toString(): StringShape {
+        if (this.isString()) {
+            return this
+        }
+
+        return Shape.from(this, String(this.getValue())).asString()
+    }
+
+    toNumber(): NumberShape {
+        if (this.isNumber()) {
+            return this
+        }
+
+        const value = this.getValue()
+        const coerced = Number(value)
+
+        //check for empty string since Number('') returns 0
+        if (isNaN(coerced) || (typeof value === 'string' && !value.trim())) {
+            throw new Error(`Cannot coerce value to number: ${value}`)
+        }
+
+        return new NumberShape({ source: this.getSource(), value: coerced })
+    }
+
+    toBoolean(): BooleanShape {
+        if (this.isBoolean()) {
+            return this
+        }
+
+        const value = this.getValue()
+        if (typeof value !== 'boolean') {
+            throw new Error(`Cannot coerce value to boolean: ${value}`)
+        }
+
+        return new BooleanShape({ source: this, value })
+    }
+
+    toRecordId(): RecordId {
+        if (this.isRecordId()) {
+            return this
+        }
+
+        throw new Error(`Coercion from ${this.getKind()} to record ID is not supported`)
+    }
+
+    getKind(): string {
+        return this.constructor.name
+    }
+
+    getDescription(): string {
+        return this.getKind()
+    }
+
+    getCode(): string {
+        const value = this.getValue()
+        if (typeof value === 'symbol') {
+            throw new Error(
+                `Shape's value is a symbol which is not supported by the default code generation behavior: ${this.getDescription()}`
+            )
+        }
+
+        return JSON5.stringify(this.getValue(), { space: 1, quote: "'" })
+    }
+}
+
+export class NoOpShape extends Shape<never> {
+    constructor(source: Source) {
+        super({ source })
+    }
+
+    override getValue(): never {
+        throw new Error('Cannot get a value from a no-op shape')
+    }
+}
+
+export class UnresolvedShape extends Shape<symbol> {
+    public static readonly CODE = 'Now.UNRESOLVED'
+    public static readonly VALUE: unique symbol = Symbol(UnresolvedShape.CODE)
+
+    override getValue() {
+        return UnresolvedShape.VALUE
+    }
+
+    override getCode(): string {
+        return UnresolvedShape.CODE
+    }
+}
+
+export class UndefinedShape extends Shape<undefined> {
+    constructor({ source }: { source: Source }) {
+        super({ source })
+    }
+
+    override getValue(): undefined {
+        return undefined
+    }
+
+    override equals(other: unknown): boolean {
+        return Shape.from(this, other).isUndefined()
+    }
+
+    override toString(): StringShape {
+        return Shape.from(this, '').asString()
+    }
+}
+
+export class DeletedShape extends UndefinedShape {}
+
+export abstract class ResolvableShape extends Shape {
+    abstract resolve(deep?: boolean): Shape
+
+    override equals(other: unknown): boolean {
+        return this.resolve(true).equals(other)
+    }
+
+    override getValue(): unknown {
+        return this.resolve(true).getValue()
+    }
+
+    override toString(): StringShape {
+        return this.resolve(true).toString()
+    }
+
+    override toNumber(): NumberShape {
+        return this.resolve(true).toNumber()
+    }
+
+    override toBoolean(): BooleanShape {
+        return this.resolve(true).toBoolean()
+    }
+
+    override toRecordId(): RecordId {
+        return this.resolve(true).toRecordId()
+    }
+}
+
+export class IdentifierShape extends ResolvableShape {
+    private readonly name: string
+    private readonly value: Shape
+
+    constructor({
+        source,
+        name,
+        value = new UnresolvedShape({ source }),
+    }: {
+        source: Source
+        name: string
+        value?: unknown
+    }) {
+        super({ source })
+        this.name = name
+        this.value = Shape.from(source, value)
+    }
+
+    getName(): string {
+        return this.name
+    }
+
+    override resolve(deep = true): Shape {
+        return deep && this.value.isResolvable() ? this.value.resolve(true) : this.value
+    }
+
+    override getCode(): string {
+        return this.getName()
+    }
+
+    override equals(other: unknown): boolean {
+        return other instanceof IdentifierShape ? this.name === other.name && super.equals(other) : super.equals(other)
+    }
+}
+
+type PropertyAccessElements = readonly [IdentifierShape, IdentifierShape, ...IdentifierShape[]]
+
+export class PropertyAccessShape extends ResolvableShape {
+    private readonly elements: PropertyAccessElements
+
+    constructor({ source, elements }: { source: Source; elements: readonly [unknown, unknown, ...unknown[]] }) {
+        super({ source })
+        this.elements = elements.map((e) =>
+            typeof e === 'string' ? new IdentifierShape({ source, name: e }) : Shape.from(source, e).asIdentifier()
+        ) as unknown as PropertyAccessElements // Annoying cast needed because `map()` doesn't respect tuples
+    }
+
+    getElements(): PropertyAccessElements {
+        return this.elements
+    }
+
+    getElement(index: number): IdentifierShape {
+        const element = this.elements[index]
+        if (!element) {
+            throw new Error(`Property access shape does not have an element at index ${index}: ${this.getCode()}`)
+        }
+
+        return element
+    }
+
+    getFirstElement(): IdentifierShape {
+        return this.getElement(0)
+    }
+
+    getLastElement(): IdentifierShape {
+        return this.getElement(this.elements.length - 1)
+    }
+
+    override resolve(deep = true) {
+        return this.getLastElement().resolve(deep)
+    }
+
+    override getCode(): string {
+        return this.elements.map((e) => e.getCode()).join('.')
+    }
+}
+
+type StringContentType = 'plain' | 'cdata'
+
+export abstract class StringShape extends Shape<string> {
+    private contentType: StringContentType = 'plain'
+
+    startsWith(substring: string): boolean {
+        return this.getValue().startsWith(substring)
+    }
+
+    endsWith(substring: string): boolean {
+        return this.getValue().endsWith(substring)
+    }
+
+    includes(substring: string): boolean {
+        return this.getValue().includes(substring)
+    }
+
+    split(separator: string): string[] {
+        return this.getValue().split(separator)
+    }
+
+    isEmpty(): boolean {
+        return this.getValue().length === 0
+    }
+
+    ifNotEmpty(): StringShape | undefined {
+        return this.isEmpty() ? undefined : this
+    }
+
+    replace(regex: string | RegExp, replacement: string): StringShape {
+        return Shape.from(this, this.getValue().replace(regex, replacement)).asString()
+    }
+
+    replaceAll(regex: string | RegExp, replacement: string): StringShape {
+        return Shape.from(this, this.getValue().replaceAll(regex, replacement)).asString()
+    }
+
+    parseJson(): ObjectShape | ArrayShape {
+        const value = this.getValue()
+        const result = JSON5.parse<unknown>(value)
+        if (!result || (!Array.isArray(result) && typeof result !== 'object')) {
+            throw new Error(`Failed to parse string shape as JSON: ${value}`)
+        }
+
+        return Shape.from(this, result).as([
+            // I have absolutely no idea why these casts are needed in this file and
+            // nowhere else. Seems like a probable TypeScript bug.
+            ObjectShape as ShapeClass<ObjectShape>,
+            ArrayShape as ShapeClass<ArrayShape>,
+        ])
+    }
+
+    withContentType(contentType: StringContentType): this {
+        this.contentType = contentType
+        return this
+    }
+
+    getContentType(): StringContentType {
+        return this.contentType
+    }
+
+    override toBoolean(): BooleanShape {
+        const value = this.getValue()
+        const trimmed = value.trim().toLowerCase()
+
+        if (trimmed === '') {
+            return new BooleanShape({ source: this, value: false })
+        }
+
+        if (!/^(true|false)$/.test(trimmed)) {
+            throw new Error(`Cannot coerce string "${value}" to boolean`)
+        }
+
+        return new BooleanShape({ source: this, value: trimmed === 'true' })
+    }
+
+    static escapeSingleQuotes(str: string): string {
+        return str.replaceAll("'", "\\'")
+    }
+
+    static escapeBackticks(str: string): string {
+        return str.replace(/[`\\]|\${/g, (char) => {
+            switch (char) {
+                case '`':
+                    return '\\`'
+                case '\\':
+                    return '\\' + char
+                case '${':
+                    return '\\${'
+                default:
+                    return char
+            }
+        })
+    }
+
+    static escapeCdataTags(str: string): string {
+        return str.replace(/]]>/g, ']]]]><![CDATA[>')
+    }
+}
+
+export class StringLiteralShape extends StringShape {
+    private readonly literalText: string
+
+    constructor({ source, literalText }: { source: Source; literalText: string | Shape }) {
+        super({ source })
+        this.literalText = typeof literalText === 'string' ? literalText : literalText.toString().getValue()
+    }
+
+    override getValue(): string {
+        return this.literalText
+    }
+
+    override getCode(): string {
+        return this.includes('\n')
+            ? `\`${StringShape.escapeBackticks(this.literalText)}\``
+            : `'${StringShape.escapeSingleQuotes(this.literalText)}'`
+    }
+}
+
+type TemplateSubstitutionValue = Shape | string | boolean | number
+export type TemplateSubstitutions =
+    | ((expression: Shape) => TemplateSubstitutionValue)
+    | globalThis.Record<number, ((expression: Shape) => TemplateSubstitutionValue) | TemplateSubstitutionValue>
+
+export class TemplateSpanShape extends StringShape {
+    private readonly literalText: string
+    private readonly expression: Shape
+
+    constructor({
+        source,
+        literalText,
+        expression,
+    }: {
+        source: Source
+        literalText: string | Shape
+        expression: Shape
+    }) {
+        super({ source })
+        this.literalText = Shape.from(source, literalText).asString().getValue()
+        this.expression = expression
+    }
+
+    getLiteralText(): string {
+        return this.literalText
+    }
+
+    getExpression(): Shape {
+        return this.expression
+    }
+
+    override getValue(
+        substitution?: ((expression: Shape) => TemplateSubstitutionValue) | TemplateSubstitutionValue
+    ): string {
+        return `${substitution instanceof Shape ? substitution.getValue() : typeof substitution === 'function' ? substitution(this.expression) : (substitution ?? this.expression.toString().getValue())}${this.literalText}`
+    }
+
+    override getCode(): string {
+        return `$\{${this.expression.getCode()}}${StringShape.escapeBackticks(this.literalText)}`
+    }
+}
+
+export class TemplateExpressionShape extends StringShape {
+    private readonly literalText: string
+    private readonly spans: TemplateSpanShape[]
+
+    constructor({
+        source,
+        literalText,
+        spans,
+    }: {
+        source: Source
+        literalText: string | Shape
+        spans?: TemplateSpanShape[]
+    }) {
+        super({ source })
+        this.literalText = Shape.from(source, literalText).asString().getValue()
+        this.spans = spans ?? []
+    }
+
+    getLiteralText(): string {
+        return this.literalText
+    }
+
+    hasSubstitution(): boolean {
+        return this.spans.length > 0
+    }
+
+    getSpans(): TemplateSpanShape[] {
+        return this.spans
+    }
+
+    override getValue(substitutions?: TemplateSubstitutions): string {
+        return `${this.literalText}${this.spans.map((s, i) => s.getValue(typeof substitutions === 'function' ? substitutions : substitutions?.[i])).join('')}`
+    }
+
+    override getCode(): string {
+        return `\`${StringShape.escapeBackticks(this.literalText)}${this.spans.map((s) => s.getCode()).join('')}\``
+    }
+}
+
+export class TaggedTemplateExpressionShape extends StringShape {
+    private readonly tag: string
+    private readonly template: TemplateExpressionShape
+
+    constructor({ source, tag, template }: { source: Source; tag: string | Shape; template: Shape }) {
+        super({ source })
+        this.tag = Shape.from(source, tag).asString().getValue()
+        this.template = template.as(TemplateExpressionShape, 'Template must be a template expression shape')
+    }
+
+    getTag(): string {
+        return this.tag
+    }
+
+    getTemplate(): TemplateExpressionShape {
+        return this.template
+    }
+
+    override getValue(substitutions?: TemplateSubstitutions): string {
+        return this.template.getValue(substitutions)
+    }
+
+    override getCode(): string {
+        return `${this.tag || ''}${this.template.getCode()}`
+    }
+}
+
+export class NumberShape extends Shape<number> {
+    private readonly value: number
+
+    constructor({ source, value }: { source: Source; value: number }) {
+        super({ source })
+        this.value = value
+    }
+
+    override getValue(): number {
+        return this.value
+    }
+}
+
+export class BooleanShape extends Shape<boolean> {
+    private readonly value: boolean
+
+    constructor({ source, value }: { source: Source; value: boolean }) {
+        super({ source })
+        this.value = value
+    }
+
+    override getValue(): boolean {
+        return this.value
+    }
+}
+
+export class ArrayShape extends Shape<unknown[]> {
+    private readonly elements: Shape[]
+
+    constructor({ source, elements }: { source: Source; elements: unknown[] }) {
+        super({ source })
+        this.elements = elements.map((e) => Shape.from(source, e))
+    }
+
+    override getValue(): unknown[] {
+        return this.elements.map((e) => e.getValue())
+    }
+
+    getElements(resolve = true): Shape[] {
+        return resolve ? this.elements.map((s) => (s.isResolvable() ? s.resolve(true) : s)) : this.elements
+    }
+
+    getElement(index: number, resolve = true): Shape {
+        return this.getElements(resolve)[index] ?? new UndefinedShape({ source: this })
+    }
+
+    hasElement(index: number): boolean {
+        return index < this.elements.length
+    }
+
+    map<T>(mapFunction: (element: Shape) => T, resolve = true): T[] {
+        return this.getElements(resolve).map(mapFunction)
+    }
+
+    override equals(other: unknown): boolean {
+        const otherShape = Shape.from(this, other)
+        if (!otherShape.isArray() || this.elements.length !== otherShape.elements.length) {
+            return false
+        }
+
+        for (const [i, element] of this.elements.entries()) {
+            if (!element.equals(otherShape.getElement(i))) {
+                return false
+            }
+        }
+
+        return true
+    }
+
+    static override from(source: Source, value: unknown): ArrayShape {
+        if (value instanceof ArrayShape) {
+            return value
+        }
+
+        value = value instanceof Shape ? value.getValue() : value
+        const coerced = Array.isArray(value) ? value : [value]
+        return new ArrayShape({ source, elements: coerced })
+    }
+
+    override getCode(): string {
+        return `[${this.map((e) => e.getCode(), false).join(', ')}]`
+    }
+}
+
+const MERGE = Symbol('MERGE')
+const coerceTo = (coerceToType: 'string' | 'number' | 'boolean' | 'cdata', value: Shape): unknown => {
+    switch (coerceToType) {
+        case 'string':
+            return value.toString()
+        case 'number':
+            return value.toNumber()
+        case 'cdata':
+            return value.toString().withContentType('cdata')
+        default:
+            return value.toBoolean()
+    }
+}
+
+class Transform {
+    constructor(
+        private readonly shape: ObjectShape,
+        private readonly resolve = true,
+        private readonly _from: [string, ...string[]] | undefined = undefined,
+        private readonly _map: ((...from: Shape[]) => unknown) | undefined = undefined,
+        private readonly _def: unknown = undefined,
+        private readonly _coerce: 'string' | 'number' | 'boolean' | 'cdata' | undefined = undefined
+    ) {}
+
+    _(to: string | typeof MERGE) {
+        const args = (this._from ?? (to === MERGE ? ([] as string[]) : [to])).map((p) =>
+            this.shape.get(p, this.resolve)
+        )
+
+        const val = (() => {
+            if (this._map) {
+                return this._map(...args)
+            } else if (this._from) {
+                return this._from.length === 1
+                    ? this.shape.get(this._from[0], this.resolve)
+                    : this.shape.pick(this._from, { resolve: this.resolve })
+            } else if (to !== MERGE) {
+                return this.shape.get(to, this.resolve)
+            } else {
+                return this.shape.properties({ resolve: this.resolve })
+            }
+        })()
+
+        if (!this._coerce) {
+            return {
+                def: this._def,
+                val,
+            }
+        } else {
+            const valShape = Shape.from(this.shape, val)
+            return {
+                def: this._def,
+                val: valShape.ifUndefined() ?? coerceTo(this._coerce, valShape),
+            }
+        }
+    }
+
+    from(...properties: [string, ...string[]]) {
+        return new Transform(this.shape, this.resolve, properties, this._map, this._def, this._coerce)
+    }
+
+    map(mapFunction: (...from: Shape[]) => unknown) {
+        return new Transform(this.shape, this.resolve, this._from, mapFunction, this._def, this._coerce)
+    }
+
+    val(value: unknown) {
+        return new Transform(this.shape, this.resolve, this._from, () => value, this._def, this._coerce)
+    }
+
+    def(value: unknown) {
+        return new Transform(this.shape, this.resolve, this._from, this._map, value, this._coerce)
+    }
+
+    toCdata() {
+        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'cdata')
+    }
+
+    toString() {
+        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'string')
+    }
+
+    toNumber() {
+        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'number')
+    }
+
+    toBoolean() {
+        return new Transform(this.shape, this.resolve, this._from, this._map, this._def, 'boolean')
+    }
+}
+
+function assignWithoutOverwriting(target: NonNullable<object>, source: unknown) {
+    if (!source) {
+        return
+    }
+
+    for (const [k, v] of Object.entries(source)) {
+        if (!(k in target)) {
+            target[k] = v
+        }
+    }
+}
+
+type ObjectPropertyOptions = {
+    nonDefaultsOnly?: boolean
+    resolve?: boolean
+}
+
+export class ObjectShape extends Shape<globalThis.Record<string, unknown>> {
+    protected readonly setProperties: globalThis.Record<string, Shape>
+    private defaultProperties: globalThis.Record<string, Shape>
+    private aliasedKeys: globalThis.Record<string, string[]>
+
+    constructor({ source, properties }: { source: Source; properties: NonNullable<object> }) {
+        super({ source })
+        if (properties instanceof ObjectShape) {
+            this.defaultProperties = properties.defaultProperties
+            this.setProperties = properties.setProperties
+            this.aliasedKeys = properties.aliasedKeys
+        } else {
+            this.defaultProperties = {}
+            this.aliasedKeys = {}
+            this.setProperties = Object.fromEntries(
+                Object.entries(properties).map(([k, v]) => [k, Shape.from(source, v)])
+            )
+        }
+    }
+
+    withAliasedKeys(aliasedKeys: globalThis.Record<string, string[]>): this {
+        this.aliasedKeys = aliasedKeys
+        return this
+    }
+
+    getAliasedKeys(): globalThis.Record<string, string[]> {
+        return this.aliasedKeys
+    }
+
+    findAliasUsed(key: string): string | undefined {
+        const aliases = this.getAliases(key)
+        const properties = this.properties({ resolve: false })
+        return aliases.find((alias) => properties[alias])
+    }
+
+    getAliases(key: string): string[] {
+        return this.aliasedKeys[key] ?? []
+    }
+
+    properties({
+        nonDefaultsOnly = false,
+        resolve = true,
+    }: ObjectPropertyOptions = {}): globalThis.Record<string, Shape> {
+        if (nonDefaultsOnly) {
+            const entries = Object.entries(this.setProperties).filter(
+                ([k, v]) => v.isDefined() && !v.equals(this.getDefault(k))
+            )
+
+            return Object.fromEntries(
+                resolve ? entries.map(([k, v]) => [k, v.isResolvable() ? v.resolve() : v]) : entries
+            )
+        }
+
+        // This logic may seem odd, but it's written this way to preserve the ordering of
+        // the set properties instead of using the ordering of the defaults.
+        const entries = [
+            ...Object.entries(this.setProperties),
+            ...Object.entries(this.defaultProperties).filter(
+                ([k]) => !this.setProperties[k] || this.setProperties[k].isUndefined()
+            ),
+        ]
+
+        return Object.fromEntries(resolve ? entries.map(([k, v]) => [k, v.isResolvable() ? v.resolve() : v]) : entries)
+    }
+
+    override getValue(nonDefaultsOnly = false): globalThis.Record<string, unknown> {
+        return Object.fromEntries(this.entries({ nonDefaultsOnly }).map(([k, v]) => [k, v.getValue()]))
+    }
+
+    get(propertyOrPath: string | [string, ...string[]], resolve = true): Shape {
+        const [property, next, ...rest] = typeof propertyOrPath === 'string' ? [propertyOrPath] : propertyOrPath
+        const propertyAliases = [property, ...this.getAliases(property)]
+        const properties = this.properties({ resolve })
+        const match = propertyAliases.find((p) => properties[p])
+        const value = match ? properties[match] : undefined
+        return (
+            (next ? value?.ifObject()?.get([next, ...rest], resolve) : value) ??
+            new UndefinedShape({ source: this.getSource() })
+        )
+    }
+
+    getDefault(property: string): Shape {
+        return this.defaultProperties[property] ?? new UndefinedShape({ source: this.getSource() })
+    }
+
+    keys(nonDefaultsOnly = false): string[] {
+        return Object.keys(this.properties({ nonDefaultsOnly }))
+    }
+
+    values(options: ObjectPropertyOptions = {}): Shape[] {
+        return Object.values(this.properties(options))
+    }
+
+    entries(options: ObjectPropertyOptions = {}): [string, Shape][] {
+        return Object.entries(this.properties(options))
+    }
+
+    has(property: string): boolean {
+        return property in this.setProperties
+    }
+
+    omit(
+        properties: string | [string, ...string[]],
+        options: ObjectPropertyOptions = {}
+    ): globalThis.Record<string, Shape> {
+        properties = typeof properties === 'string' ? [properties] : properties
+        const regex = new RegExp(`^(${properties.map((p) => p.replaceAll('$', '\\$')).join('|')})$`)
+        return Object.fromEntries(
+            this.entries(options)
+                .filter(([k]) => !regex.test(k))
+                .map(([k, v]) => [k, v])
+        )
+    }
+
+    pick(
+        properties: string | [string, ...string[]],
+        options: ObjectPropertyOptions = {}
+    ): globalThis.Record<string, Shape> {
+        properties = typeof properties === 'string' ? [properties] : properties
+        const regex = new RegExp(`^(${properties.join('|')})$`)
+        return Object.fromEntries(
+            this.entries(options)
+                .filter(([k]) => regex.test(k))
+                .map(([k, v]) => [k, v])
+        )
+    }
+
+    private setDefaults(defaults: globalThis.Record<string, unknown>): this {
+        this.defaultProperties = Object.fromEntries(
+            Object.entries(defaults).map(([k, v]) => [k, Shape.from(this.getSource(), v)])
+        )
+
+        for (const [k, v] of Object.entries(this.setProperties)) {
+            if (v.isObject() && this.defaultProperties[k]?.isObject()) {
+                v.setDefaults(this.defaultProperties[k].getValue())
+            }
+        }
+
+        return this
+    }
+
+    transform(
+        schema: (utils: { $: Transform; merge: typeof MERGE }) => {
+            [P in string | typeof MERGE]?: Transform
+        },
+        resolve = true
+    ) {
+        const properties = {}
+        const defaults = {}
+
+        const definedSchema = schema({ merge: MERGE, $: new Transform(this, resolve) })
+        for (const to of [...Object.keys(definedSchema), MERGE] as const) {
+            if (definedSchema[to]) {
+                const result = definedSchema[to]._(to)
+                if (to === MERGE) {
+                    const { val, def } = result
+                    if (val && (typeof val !== 'object' || Array.isArray(val))) {
+                        throw new Error('Cannot merge non-object value')
+                    }
+
+                    if (def && (typeof def !== 'object' || Array.isArray(def))) {
+                        throw new Error('Cannot merge non-object default value')
+                    }
+
+                    if (val instanceof ObjectShape) {
+                        assignWithoutOverwriting(properties, val.setProperties)
+                        assignWithoutOverwriting(defaults, val.defaultProperties)
+                    } else {
+                        assignWithoutOverwriting(properties, val)
+                    }
+
+                    if (def instanceof ObjectShape) {
+                        assignWithoutOverwriting(defaults, def.setProperties)
+                    } else if (def) {
+                        assignWithoutOverwriting(defaults, def)
+                    }
+                } else {
+                    properties[to] = result.val
+                    if (result.def !== undefined) {
+                        defaults[to] = result.def
+                    }
+                }
+            }
+        }
+
+        return new ObjectShape({
+            source: this.getSource(),
+            properties,
+        }).setDefaults(defaults)
+    }
+
+    merge(other: NonNullable<object>): ObjectShape {
+        const mergedProperties = { ...this.setProperties }
+        const mergedDefaults = { ...this.defaultProperties }
+
+        for (const [a, b] of [
+            [mergedProperties, other instanceof ObjectShape ? other.setProperties : other],
+            [mergedDefaults, other instanceof ObjectShape ? other.defaultProperties : {}],
+        ] as const) {
+            for (const [key, v] of Object.entries(b)) {
+                const value = Shape.from(this, v)
+                if (!(key in a) && value.isUndefined()) {
+                    // Don't add properties that are undefined
+                } else if (a[key]?.equals(value)) {
+                    // Don't overwrite properties that are equal
+                } else if (a[key]?.isObject() && value.isObject()) {
+                    a[key].merge(value) // Merge objects recursively
+                } else {
+                    a[key] = value
+                }
+            }
+        }
+
+        return new ObjectShape({
+            source: this.getSource(),
+            properties: mergedProperties,
+        })
+            .setDefaults(mergedDefaults)
+            .setCreator(this.getCreator())
+    }
+
+    override equals(other: unknown): boolean {
+        const otherShape = Shape.from(this, other)
+        if (!otherShape.isObject() || this.keys().length !== otherShape.keys().length) {
+            return false
+        }
+
+        for (const [k, v] of this.entries()) {
+            if (!v.equals(otherShape.get(k))) {
+                return false
+            }
+        }
+
+        return true
+    }
+
+    override getCode(): string {
+        return `{\n    ${this.entries({ nonDefaultsOnly: true, resolve: false })
+            .map(([k, v]) => `${ObjectShape.quotePropertyNameIfNeeded(k)}: ${v.getCode()}`)
+            .join(',\n    ')}\n}`
+    }
+
+    static quotePropertyNameIfNeeded(name: string): string {
+        return /[^\w$]/.test(name) ? `'${name}'` : name
+    }
+}
+
+export class CallExpressionShape extends Shape {
+    private readonly callee: string
+    private readonly args: ArrayShape
+
+    constructor({ source, callee, args }: { source: Source; callee: string; args: unknown[] }) {
+        super({ source })
+        this.callee = callee
+        this.args = new ArrayShape({ source, elements: args })
+    }
+
+    getCallee(): string {
+        return this.callee
+    }
+
+    getArguments(resolve = true): Shape[] {
+        return this.args.getElements(resolve)
+    }
+
+    getArgument(index: number, resolve = true): Shape {
+        return this.args.getElement(index, resolve)
+    }
+
+    hasArgument(index: number): boolean {
+        return this.args.hasElement(index)
+    }
+
+    override getDescription(): string {
+        return `${this.getKind()} (${this.callee})`
+    }
+
+    override getCode(): string {
+        return `${this.callee}(${this.args.map((a) => a.getCode(), false).join(', ')})`
+    }
+}
+
+export class SourceFileShape extends StringShape {
+    private readonly path: string
+    private readonly content: string
+
+    constructor({ file }: { file: ts.SourceFile }) {
+        super({ source: file })
+        this.path = file.getFilePath()
+        this.content = file.getFullText()
+    }
+
+    getPath(): string {
+        return this.path
+    }
+
+    getBaseName(): string {
+        return path.basename(this.path)
+    }
+
+    getExtension(): string {
+        return path.extname(this.path)
+    }
+
+    getContent(): string {
+        return this.content
+    }
+
+    override getSource(): ts.SourceFile {
+        return this.getOriginalNode().asKindOrThrow(ts.SyntaxKind.SourceFile)
+    }
+
+    override getValue(): string {
+        return this.getContent()
+    }
+
+    override getCode(): string {
+        return this.getContent()
+    }
+}
+
+export class ElementAccessExpressionShape extends Shape {
+    private readonly callee: string
+    private readonly arg: StringShape | NumberShape
+
+    constructor({ source, callee, arg }: { source: Source; callee: string; arg: unknown }) {
+        super({ source })
+        this.callee = callee
+        this.arg = Shape.from(source, arg)
+            .pipe((e) => (e.isResolvable() ? e.resolve() : e))
+            .as(
+                [
+                    // I have absolutely no idea why these casts are needed in this file and
+                    // nowhere else. Seems like a probable TypeScript bug.
+                    StringShape as ShapeClass<StringShape>,
+                    NumberShape as ShapeClass<NumberShape>,
+                ],
+                `Invalid argument to element access expression: ${arg instanceof Shape ? arg.getDescription() : JSON.stringify(arg)}`
+            )
+    }
+
+    getCallee(): string {
+        return this.callee
+    }
+
+    getArg(): StringShape | NumberShape {
+        return this.arg
+    }
+}
+
+export class VariableStatementShape extends Shape {
+    private readonly variableName: IdentifierShape
+    private readonly initializer: Shape
+    private readonly _isExported: boolean
+
+    constructor({
+        source,
+        variableName,
+        initializer,
+        isExported = false,
+    }: {
+        source: Source
+        variableName: IdentifierShape | string
+        initializer: unknown
+        isExported?: boolean
+    }) {
+        super({ source })
+        this.variableName =
+            variableName instanceof Shape ? variableName : new IdentifierShape({ source, name: variableName })
+        this.initializer = Shape.from(source, initializer)
+        this._isExported = isExported
+    }
+
+    getVariableName(): IdentifierShape {
+        return this.variableName
+    }
+
+    getInitializer(): Shape {
+        return this.initializer
+    }
+
+    isExported(): boolean {
+        return this._isExported
+    }
+
+    override getCode(): string {
+        return `${this.isExported() ? 'export ' : ''}const ${this.getVariableName().getName()} = ${this.getInitializer().getCode()}`
+    }
+}
+
+function getDefaultCategoryFromTable(table: string): InstallCategory {
+    return table === 'sys_app' ? 'scope' : 'update'
+}
+
+function getInstallCategoryFromInstallMethod(installMethod: string): InstallCategory {
+    return installMethod === 'demo' ? 'unload.demo' : 'unload'
+}
+
+export function getInstallCategory(source: Source, table: string): InstallCategory {
+    let installCategory: InstallCategory = getDefaultCategoryFromTable(table)
+    if (source instanceof CallExpressionShape) {
+        const installMethod = source.getArgument(0).ifObject()?.get(['$meta', 'installMethod']).ifString()?.getValue()
+        if (installMethod) {
+            installCategory = getInstallCategoryFromInstallMethod(installMethod)
+        }
+    }
+    return installCategory
+}
+
+export type Action = 'INSERT_OR_UPDATE' | 'UPDATE' | 'DELETE' | 'delete_multiple'
+
+export class Record extends ObjectShape {
+    private readonly id: RecordId
+    private readonly related: Record[] = []
+    private readonly action: Action
+    private readonly installCategory: InstallCategory
+
+    constructor({
+        source,
+        id,
+        properties,
+        action = 'INSERT_OR_UPDATE',
+        installCategory = getDefaultCategoryFromTable(id.getTable()),
+    }: {
+        source: Source
+        id: RecordId
+        properties: NonNullable<object>
+        action?: Action
+        installCategory?: InstallCategory
+    }) {
+        super({ source, properties })
+        this.action = action
+        this.id = id
+        this.installCategory = installCategory
+    }
+
+    static isDeleteAction(action: Action): boolean {
+        return action === 'DELETE' || action === 'delete_multiple'
+    }
+
+    getId(): RecordId {
+        return this.id
+    }
+
+    getInstallCategory(): InstallCategory {
+        return this.installCategory
+    }
+
+    getTable(): string {
+        return this.id.getTable()
+    }
+
+    getAction(): Action {
+        return this.action
+    }
+
+    isDeleted(): boolean {
+        return Record.isDeleteAction(this.getAction())
+    }
+
+    getUpdateName(): string {
+        return this.id.getUpdateName()
+    }
+
+    with(...related: Record[]): this {
+        this.related.length = 0
+        this.related.push(...related)
+        return this
+    }
+
+    flat(): Record[] {
+        return [this, ...this.related.flatMap((r) => r.flat())]
+    }
+
+    getCount(): number {
+        return 1 + this.related.reduce((count, r) => count + r.getCount(), 0)
+    }
+
+    override merge(other: NonNullable<object>): Record {
+        return new Record({
+            source: this.getSource(),
+            id: this.getId(),
+            action: other instanceof Record ? other.getAction() : this.getAction(),
+            installCategory: this.getInstallCategory(),
+            properties: super.merge(other),
+        }).setCreator(this.getCreator())
+    }
+
+    override equals(other: unknown): boolean {
+        return this.getId().equals(other)
+    }
+
+    /**
+     * Useful when you need to know if this record is equal to another not
+     * just in terms of its identity but also its data.
+     */
+    strictEquals(other: unknown): boolean {
+        if (!this.equals(other)) {
+            return false
+        }
+
+        if (!(other instanceof Record)) {
+            return false
+        }
+
+        return this.getAction() === other.getAction() && super.equals(other)
+    }
+
+    override setCreator(creator: Plugin | undefined, overwrite = false): this {
+        this.related.forEach((r) => r.setCreator(creator, overwrite))
+        return super.setCreator(creator, overwrite)
+    }
+
+    override toRecordId(): RecordId {
+        return this.id
+    }
+
+    override toString(): StringShape {
+        return this.id
+    }
+}
+
+export type CoalesceKeys = globalThis.Record<string, string | RecordId>
+export type ResolvedCoalesceKeys = globalThis.Record<string, string>
+export class RecordId extends StringShape {
+    private readonly table: string
+    private readonly guid: string | (() => string)
+    private readonly keys: CoalesceKeys | undefined
+    private readonly nowIdKey: string | number | undefined
+
+    constructor({
+        source,
+        table,
+        guid,
+        keys: rawKeys,
+        nowIdKey,
+    }: {
+        source: Source
+        table: string
+        guid: string | (() => string)
+        keys?: CoalesceKeys | ObjectShape | undefined
+        nowIdKey?: string | number | undefined
+    }) {
+        const keys =
+            rawKeys instanceof ObjectShape
+                ? Object.fromEntries(rawKeys.entries().map(([k, v]) => [k, v.ifString()?.getValue() ?? v.toRecordId()]))
+                : rawKeys
+
+        if (keys && Object.keys(keys).length <= 0) {
+            throw new Error('Failed to create RecordId shape. Coalesce keys must contain at least one entry.')
+        }
+
+        super({ source })
+        this.table = table
+        this.guid = guid
+        this.keys = keys
+        this.nowIdKey = nowIdKey
+    }
+
+    getTable(): string {
+        return this.table
+    }
+
+    getGuidProducer(): string | (() => string) {
+        return this.guid
+    }
+
+    getNowIdKey(): string | number | undefined {
+        return this.nowIdKey
+    }
+
+    getKeys(): CoalesceKeys | undefined {
+        return this.keys
+    }
+
+    /**
+     * Similar to `getKeys`, but resolves any nested record IDs to their GUID values
+     */
+    resolveKeys(): ResolvedCoalesceKeys | undefined {
+        if (!this.keys) {
+            return undefined
+        }
+
+        return Object.fromEntries(
+            Object.entries(this.keys).map(([k, v]) => [k, typeof v === 'string' ? v : v.getValue()])
+        )
+    }
+
+    getKey(key: string): string | RecordId | undefined {
+        return this.getKeys()?.[key]
+    }
+
+    getPrimaryKey(): string {
+        const keyValues = Object.values(this.keys ?? {})
+        const [primaryKeyValue] = keyValues
+        if (keyValues.length !== 1 || !primaryKeyValue || typeof primaryKeyValue !== 'string') {
+            throw new Error("Tried to get primary key of record ID that doesn't have one")
+        }
+
+        return primaryKeyValue
+    }
+
+    hasPrimaryKey(): boolean {
+        return !!this.keys && Object.keys(this.keys).length === 1
+    }
+
+    getUpdateName(): string {
+        // TODO: Provide a way to override this for non-standard coalesce strategies, or
+        //  just hard-code the very short list of special cases from UpdateName.java
+        return `${this.table}_${this.getValue()}`
+    }
+
+    override getValue(): string {
+        return typeof this.guid === 'string' ? this.guid : this.guid()
+    }
+
+    override equals(other: unknown): boolean {
+        const otherShape = Shape.from(this, other)
+        if (otherShape.isRecord()) {
+            return this.equals(otherShape.getId())
+        }
+
+        if (otherShape.isRecordId()) {
+            return (
+                this.getTable() === otherShape.getTable() &&
+                (this.getValue() === otherShape.getValue() ||
+                    (this.keys !== undefined && _.isEqual(this.keys, otherShape.keys)))
+            )
+        }
+
+        return (this.hasPrimaryKey() && otherShape.equals(this.getPrimaryKey())) || super.equals(other)
+    }
+
+    override getCode(): string {
+        return `'${this.hasPrimaryKey() ? this.getPrimaryKey() : this.getValue()}'`
+    }
+}