@cap-js/cds-typer 0.38.0 → 0.39.0

package/lib/visitor.js

@@ -6,13 +6,13 @@ const { SourceFile, FileRepository, Buffer, Path } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./resolution/resolver')
 const { LOG } = require('./logging')
-const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf, createIntersectionOf } = require('./printers/wrappers')
+const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf, createIntersectionOf, createBrandedType } = require('./printers/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
 const { getBaseDefinitions } = require('./components/basedefs')
 const { EntityRepository, asIdentifier } = require('./resolution/entity')
-const { last } = require('./components/identifier')
+const { last, Identifier } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
 const { configuration } = require('./config')
 const { createMember } = require('./components/class')
@@ -103,7 +103,13 @@ class Visitor {
     #printStaticActions(entity, clean, buffer, ancestors, file) {
         // TODO: refactor away! All these printing functionalities need to go
         const actions = Object.entries(entity.actions ?? {})
-        const inherited = ancestors.map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.actions`)
+        const inherited = ancestors
+            // Filter out ancestors whose class name matches the current class to avoid circular references
+            .filter(a => {
+                const ancestorClassName = isType(a.csn) ? a.entityName : a.inflection.singular?.plain
+                return ancestorClassName !== clean
+            })
+            .map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.actions`)
 
         const typeBuffer = buffer.createSubBuffer()
         if (actions.length) {
@@ -143,6 +149,12 @@ class Visitor {
     #printStaticKeys(buffer, clean, ancestors, file) {
         const ancestorKeys = ancestors
             .filter(a => Object.entries(a.csn.keys ?? {}).length)
+            // Filter out ancestors whose class name matches the current class to avoid circular references
+            // This happens when a nested entity has the same @singular as its ancestor
+            .filter(a => {
+                const ancestorClassName = isType(a.csn) ? a.entityName : a.inflection.singular?.plain
+                return ancestorClassName !== clean
+            })
             .map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.keys`)
         buffer.add(createMember({
             name: 'keys',
@@ -173,38 +185,21 @@ class Visitor {
      * - the function A(B) to mix the aspect into another class B
      * - the const AXtended which represents the entity A with all of its aspects mixed in (this const is not exported)
      * - the type A to use for external typing and is derived from AXtended.
-     * @param {string} fq - the name of the entity
+     * @param {Identifier | string} fq - the name of the entity
      * @param {EntityCSN} entity - the pointer into the CSN to extract the elements from
      * @param {Buffer} buffer - the buffer to write the resulting definitions into
      * @param {{cleanName?: string}} options - additional options
      */
     #aspectify(fq, entity, buffer, options = {}) {
+        if (typeof fq !== 'string') fq = fq.plain
         const info = this.entityRepository.getByFqOrThrow(fq)
-        const clean = options?.cleanName ?? info.withoutNamespace
+        const clean = new Identifier(options?.cleanName ?? info.withoutNamespace).plain
         const { namespace } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
+        const { isNormalised = false, originalName = null } = options
         const identSingular = (/** @type {string} */name) => name  // FIXME: remove
-        //const identAspect = name => `_${name}Aspect`
         /** @param {string} name - the name */
         const identAspect = name => `_${name}Aspect`
-        /**
-         * @param {object} options - options
-         * @param {Path} [options.ns] - namespace
-         * @param {string} options.clean - the clean name of the entity
-         * @param {string} options.fq - fully qualified name
-         * @returns {string} the local identifier
-         */
-        // FIXME: replace with resolution/entity::asIdentifier
-        const toLocalIdent = ({ns, clean, fq}) => {
-            // types are not inflected, so don't change those to singular
-            const csn = this.csn.definitions[fq]
-            const ident = isType(csn)
-                ? clean
-                : this.resolver.inflect({csn, plainName: clean}).singular
-            return !ns || ns.isCwd(file.path.asDirectory())
-                ? ident
-                : `${ns.asIdentifier()}.${ident}`
-        }
         // remove the ancestry of projections/ views.
         // They explicitly define their properties.
         // But at the same time they also carry their .includes clause, which can
@@ -225,13 +220,23 @@ class Visitor {
 
         const ancestorsAspects = ancestorInfos
             .reverse() // reverse so that own aspect A is applied before extensions B,C: B(C(A(Entity)))
-            .reduce((wrapped, ancestor) => `${asIdentifier({info: ancestor, wrapper: name => `_${name}Aspect`, relative: file.path})}(${wrapped})`, 'Base')
+            .reduce((wrapped, ancestor) => `${asIdentifier({info: ancestor, wrapper: name => identAspect(name), relative: file.path})}(${wrapped})`, 'Base')
+
+        // Check if the aspect function name would collide with an ancestor's aspect function name
+        // This can happen in nested namespaces where the entity has the same @singular as its ancestor
+        const hasNamingCollision = ancestorInfos.some(ancestor => {
+            const ancestorName = isType(ancestor.csn) ? ancestor.entityName : ancestor.inflection.singular?.plain
+            return ancestorName === clean
+        })
+
+        // If there's a naming collision, use a unique name based on the entity name to avoid shadowing
+        const aspectFunctionName = hasNamingCollision ? identAspect(info.entityName) : identAspect(clean)
 
         const inheritedElements = !isViewOrProjection(entity) ? info.inheritedElements : null
-        this.contexts.push({ entity: fq })
+        this.contexts.push({ entity: new Identifier(fq) })
 
         // CLASS ASPECT
-        buffer.addIndentedBlock(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`, () => {
+        buffer.addIndentedBlock(`export function ${aspectFunctionName}<TBase extends new (...args: any[]) => object>(Base: TBase) {`, () => {
             buffer.addIndentedBlock(`return class ${clean} extends ${ancestorsAspects} {`, () => {
                 /** @type {import('./typedefs').resolver.EnumCSN[]} */
                 const enums = []
@@ -255,7 +260,8 @@ class Visitor {
                                 } else {
                                     const kelement = Object.assign(Object.create(originalKeyElement), {
                                         isRefNotNull: !!element.notNull || !!element.key,
-                                        key: element.key
+                                        key: element.key,
+                                        _targetEntity: element.target  // Track the target entity for inline enum resolution
                                     })
                                     this.visitElement({name: foreignKey, element: kelement, file, buffer, resolverOptions})
                                 }
@@ -271,10 +277,12 @@ class Visitor {
 
                 for (const e of enums) {
                     const eDoc = docify(e.doc)
+                    // Normalize property name to handle delimited identifiers
+                    const normalizedPropertyName = new Identifier(e.name).normalised.plain
                     buffer.add(eDoc)
                     buffer.add(createMember({
                         name: e.name,
-                        initialiser: propertyToInlineEnumName(clean, e.name),
+                        initialiser: propertyToInlineEnumName(clean, normalizedPropertyName),
                         isStatic: true,
                     }))
                     if (typeof e?.type !== 'string' && e?.type?.ref) {
@@ -305,7 +313,7 @@ class Visitor {
                             }
                         } catch { /* ignore */ }
                     }
-                    file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), buffer, eDoc)
+                    file.addInlineEnum(clean, fq, normalizedPropertyName, csnToEnumPairs(e, {unwrapVals: true}), buffer, eDoc)
                 }
 
                 if ('kind' in entity) {
@@ -328,7 +336,17 @@ class Visitor {
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
         docify(entity.doc).forEach(d => { buffer.add(d) })
-        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(fq, clean).join('\n')}}`)
+
+        // Add documentation if the name was normalized
+        if (isNormalised && originalName) {
+            buffer.add(docify([
+                `This class represents "${originalName}" and can be accessed via:`,
+                `- Named import: \`import { ${clean} } from '...'\``,
+                `- Aliased import: \`import { "${originalName}" as MyAlias } from '...'\`!`
+            ]))
+        }
+
+        buffer.add(`export class ${identSingular(clean)} extends ${aspectFunctionName}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(fq, clean).join('\n')}}`)
         this.contexts.pop()
     }
 
@@ -350,27 +368,28 @@ class Visitor {
         const info = this.entityRepository.getByFqOrThrow(fq)
         const { namespace: ns, entityName: clean, inflection, scope } = info
         const file = this.fileRepository.getNamespaceFile(ns)
-        let { singular, plural } = inflection
+        let { singular, plural } = inflection ?? {}
 
         // trimNamespace does not properly detect scoped entities, like A.B where both A and B are
         // entities. So to see if we would run into a naming collision, we forcefully take the last
         // part of the name, so "A.B" and "A.Bs" just become "B" and "Bs" to be compared.
-        if (last(plural) === `${last(singular)}_`) {
+        if (last(plural?.normalised.plain) === `${last(singular?.normalised.plain ?? '')}_`) {
             LOG.warn(
                 `Derived singular and plural forms for '${singular}' are the same. This usually happens when your CDS entities are named following singular flexion. Consider naming your entities in plural or providing '@singular:'/ '@plural:' annotations to have a clear distinction between the two. Plural form will be renamed to '${plural}' to avoid compilation errors within the output.`
             )
         }
 
+        // use non-normalised identifier to facilitate lookup in CSN
+        const namespacedSingular = `${ns.asNamespace()}.${singular.plain}`
         // as types are not inflected, their singular will always clash and there is also no plural for them anyway -> skip
         // if the user defined their entities in singular form we would also have a false positive here -> skip
-        const namespacedSingular = `${ns.asNamespace()}.${singular}`
         if (!isType(entity) && namespacedSingular !== fq && namespacedSingular in this.csn.definitions) {
             LOG.error(
-                `Derived singular '${singular}' for your entity '${fq}', already exists. The resulting types will be erronous. Consider using '@singular:'/ '@plural:' annotations in your model or move the offending declarations into different namespaces to resolve this collision.`
+                `Derived singular '${singular.plain}' for your entity '${fq}', already exists. The resulting types will be erronous. Consider using '@singular:'/ '@plural:' annotations in your model or move the offending declarations into different namespaces to resolve this collision.`
             )
         }
-        file.addClass(singular, fq)
-        file.addClass(plural, fq)
+        file.addClass(singular.normalised.plain, fq)
+        file.addClass(plural.normalised.plain, fq)
 
         const parent = this.resolver.resolveParent(entity.name)
         const buffer = parent && parent.kind === 'entity'
@@ -380,15 +399,26 @@ class Visitor {
         if (scope?.length > 0) {
             /** @param {string} n - name of entity */
             const scoped = n => [...scope, n].join('.')
-            file.addInflection(scoped(singular), scoped(plural), scoped(clean))
+            file.addInflection({singular: scoped(singular.normalised.plain), plural: scoped(plural.normalised.plain), original: scoped(clean), isNormalised: singular.normalised.isChangedFromNormalisation})
         } else {
-            file.addInflection(singular, plural, clean)
+            file.addInflection({singular:singular.normalised.plain, plural: plural.normalised.plain, original: clean, isNormalised: singular.normalised.isChangedFromNormalisation})
         }
 
-        this.#aspectify(fq, entity, buffer, { cleanName: singular })
+        buffer.add(`// entity '${singular.scoped}'`)  // identifiers, especially normalised ones, can get really butchered, so this is helpful for debugging
 
-        buffer.add(overrideNameProperty(singular, entity.name))
-        buffer.add(`Object.defineProperty(${singular}, 'is_singular', { value: true })`)
+        this.#aspectify(fq, entity, buffer, {
+            cleanName: singular.normalised.plain,
+            isNormalised: singular.normalised.isChangedFromNormalisation,
+            originalName: singular.plain
+        })  // FIXME: pass Identifier verbatim?
+
+        buffer.add(overrideNameProperty(singular.normalised.plain, entity.name))
+        buffer.add(`Object.defineProperty(${singular.normalised.plain}, 'is_singular', { value: true })`)
+
+        // Add export alias if the name was normalized
+        if (singular.normalised.isChangedFromNormalisation) {
+            buffer.add(`export { ${singular.normalised.plain} as "${singular.plain}" }`)
+        }
 
         // PLURAL
         // types do not receive a plural
@@ -406,17 +436,32 @@ class Visitor {
         const { fullyQualifiedName: fq, csn: entity } = info
         let { singular, plural } = info.inflection
 
-        if (plural.includes('.')) {
+        if (plural.plain.includes('.')) {
             // Foo.text -> namespace Foo { class text { ... }}
-            plural = last(plural)
+            plural.plain = last(plural.plain)
         }
         // plural can not be a type alias to $singular[] but needs to be a proper class instead,
         // so it can get passed as value to CQL functions.
-        const additionalProperties = this.#staticClassContents(fq, singular, true)
+        const additionalProperties = this.#staticClassContents(fq, singular.plain, true)
         additionalProperties.push('$count?: number')
+
+        // Add documentation if the name was normalized
+        if (plural.normalised.isChangedFromNormalisation) {
+            buffer.add(docify([
+                `This class represents the plural form of "${singular.plain}". It is not a type alias to "${singular.plain}[]" but a separate class, which can be used as value (e.g., for CQL functions). It can be accessed via:`,
+                `- Named import: \`import { ${plural.normalised.plain} } from '...'\``,
+                `- Aliased import: \`import { "${plural.plain}" as MyAlias } from '...'\`!`
+            ]))
+        }
+
         buffer.add(docify(entity.doc))
-        buffer.add(`export class ${plural} extends Array<${singular}> {${additionalProperties.join('\n')}}`)
-        buffer.add(overrideNameProperty(plural, entity.name))
+        buffer.add(`export class ${plural.normalised.plain} extends Array<${singular.normalised.plain}> {${additionalProperties.join('\n')}}`)
+        buffer.add(overrideNameProperty(plural.normalised.plain, entity.name))
+
+        // Add export alias if the name was normalized
+        if (plural.normalised.isChangedFromNormalisation) {
+            buffer.add(`export { ${plural.normalised.plain} as "${plural.plain}" }`)
+        }
     }
 
     /**
@@ -447,15 +492,13 @@ class Visitor {
      */
     #stringifyFunctionParamType(type, file) {
         // if type.type is not 'cds.String', 'cds.Integer', ..., then we are actually looking
-        // at a named enum type. In that case also resolve that type name
+        //  at a named enum type. In that case also resolve that type name
         const isNamedEnumType = isEnum(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)
         if (isNamedEnumType) return stringifyEnumType(csnToEnumPairs(type))
         const paramType = this.resolver.resolveAndRequire(type, file)
         return this.inlineDeclarationResolver.getPropertyDatatype(
             paramType,
-            paramType.typeInfo.isArray || paramType.typeInfo.isDeepRequire
-                ? paramType.typeName
-                : paramType.typeInfo.inflection.singular
+            paramType.typeName  // Use typeName which includes namespace prefix
         )
     }
 
@@ -471,12 +514,10 @@ class Visitor {
         const params = this.#stringifyFunctionParams(operation.params, file)
         const returnType = operation.returns
             ? this.resolver.resolveAndRequire(operation.returns, file)
-            : { typeName: 'void', typeInfo: { plainName: 'void', isArray: false, inflection: { singular: 'void', plural: 'void' } } }
+            : { typeName: 'void', typeInfo: { plainName: 'void', isArray: false, inflection: { singular: new Identifier('void'), plural: new Identifier('void') } } }
         let returns = this.inlineDeclarationResolver.getPropertyDatatype(
             returnType,
-            returnType.typeInfo.isArray
-                ? returnType.typeName
-                : returnType.typeInfo.inflection.singular
+            returnType.typeName  // Use typeName which includes namespace prefix
         )
         if (operation.returns) {
             // operation results may be a Promise
@@ -486,7 +527,12 @@ class Visitor {
         // Prevent positional call style there.
         // TODO find a better way to detect ABAP RFC actions
         const isRFC = Object.values(operation.params ?? {}).some(p => Object.keys(p).some(k => k.startsWith('@RFC')))
-        file.addOperation(last(fq), params, returns, kind, docify(operation.doc), {named: true, positional: !isRFC})
+        // Normalize the operation name to handle delimited identifiers
+        const originalName = last(fq)
+        const identifier = new Identifier(originalName)
+        const normalizedName = identifier.normalised.plain
+        const originalNameIfDifferent = identifier.normalised.plain !== identifier.plain ? originalName : undefined
+        file.addOperation(normalizedName, params, returns, kind, docify(operation.doc), {named: true, positional: !isRFC}, originalNameIfDifferent)
         file.addImport(baseDefinitions.path)
     }
 
@@ -498,15 +544,32 @@ class Visitor {
         LOG.debug(`Printing type ${fq}:\n${JSON.stringify(type, null, 2)}`)
         const { namespace, entityName } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
+
+        // Normalize the entity name to handle reserved words and special characters
+        const identifier = new Identifier(entityName)
+        const normalizedName = identifier.normalised.plain
+
         // skip references to enums.
         // "Base" enums will always have a builtin type (don't skip those).
         // A type referencing an enum E will be considered an enum itself and have .type === E (skip).
         if (isEnum(type) && !isReferenceType(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)) {
-            file.addEnum(fq, entityName, csnToEnumPairs(type), docify(type.doc))
+            file.addEnum(fq, normalizedName, csnToEnumPairs(type), docify(type.doc))
+            // Add export alias if the normalized name differs from the original
+            if (normalizedName !== identifier.plain) {
+                file.types.add(`export { ${normalizedName} as "${identifier.plain}" }`)
+            }
         } else {
             const isEnumReference = typeof type.type === 'string' && isEnum(this.csn.definitions[type?.type])
+            const resolved = this.resolver.resolveAndRequire(type, file)
+            if (configuration.brandedPrimitiveTypes && resolved.typeInfo.isBuiltin) {
+                resolved.typeName = createIntersectionOf(resolved.typeName, createBrandedType(fq))
+            }
             // alias
-            file.addType(fq, entityName, this.resolver.resolveAndRequire(type, file).typeName, isEnumReference)
+            file.addType(fq, normalizedName, resolved.typeName, isEnumReference)
+            // Add export alias if the normalized name differs from the original
+            if (normalizedName !== identifier.plain) {
+                file.types.add(`export { ${normalizedName} as "${identifier.plain}" }`)
+            }
         }
         // TODO: annotations not handled yet
     }
@@ -543,6 +606,14 @@ class Visitor {
         buffer.add('// event')
         // only declare classes, as their properties are not optional, so we don't have to do awkward initialisation thereof.
         buffer.addIndentedBlock(`export declare class ${entityName} {`, () => {
+            buffer.add(createMember({
+                name: 'kind',
+                type: stringIdent(event.kind),
+                isStatic: true,
+                isReadonly: true,
+                isDeclare: false,
+                isOverride: false
+            }))
             const propOpt = configuration.propertiesOptional
             // FIXME: shouldn't need to change config here! Idea: init Visitor with .options fed from config, then manipulate that
             configuration.propertiesOptional = false
@@ -568,10 +639,12 @@ class Visitor {
         // file.addImport(new Path(['cds'], '')) TODO make sap/cds import work
         buffer.addIndentedBlock('export default class {', () => {
             Object.entries(service.operations ?? {}).forEach(([name, {doc}]) => {
+                // Normalize the operation name to match how it's exported in #printOperation
+                const normalizedName = new Identifier(name).normalised.plain
                 buffer.add(docify(doc))
                 buffer.add(createMember({
-                    name,
-                    type: `typeof ${name}`,
+                    name: normalizedName,
+                    type: `typeof ${normalizedName}`,
                     isStatic: true,
                     isReadonly: true,
                     isDeclare: true,
@@ -636,7 +709,7 @@ class Visitor {
      * ```
      */
     isSelfReference(fq) {
-        return fq === this.contexts.at(-1)?.entity
+        return fq === this.contexts.at(-1)?.entity.scoped
     }
 
     /**
@@ -647,7 +720,7 @@ class Visitor {
      * @param {SourceFile} options.file - the namespace file the surrounding entity is being printed into.
      * @param {Buffer} [options.buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
      * @param {TypeResolveOptions} [options.resolverOptions] - custom type resolver options
-     * @returns @see InlineDeclarationResolver.visitElement
+     * @returns {ReturnType<import('./components/inline').FlatInlineDeclarationResolver['visitElement']>}
      */
     visitElement({name, element, file, buffer = file.classes, resolverOptions}) {
         return this.inlineDeclarationResolver.visitElement({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
   "repository": "github:cap-js/cds-typer",
@@ -155,6 +155,11 @@
               "type": "boolean",
               "description": "If set to true, the typescript build task will not be registered/ executed.\nThis value must be set in your project configuration.\nPassing it as parameter to the cds-typer CLI has no effect.",
               "default": true
+            },
+            "branded_primitive_types": {
+              "type": "boolean",
+              "description": "If set to true, generated primitive types will be branded to prevent accidental mixing of types with the same underlying primitive.\nE.g., type CustomerID = string & { __brand: 'CustomerID' }",
+              "default": false
             }
           }
         }