@cap-js/cds-typer 0.24.0 → 0.25.0

package/lib/visitor.js

@@ -2,9 +2,9 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, isType, isProjection, getMaxCardinality } = require('./csn')
+const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, isType, isProjection, getMaxCardinality, isViewOrProjection, isEnum } = require('./csn')
 // eslint-disable-next-line no-unused-vars
-const { SourceFile, FileRepository, Buffer } = require('./file')
+const { SourceFile, FileRepository, Buffer, Path } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./resolution/resolver')
 const { LOG } = require('./logging')
@@ -13,14 +13,18 @@ const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnu
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
 const { baseDefinitions } = require('./components/basedefs')
-const { EntityRepository } = require('./resolution/entity')
+const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
+const { getPropertyModifiers } = require('./components/property')
 
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
 /** @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters */
 /** @typedef {import('./typedefs').visitor.VisitorOptions} VisitorOptions */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
+/** @typedef {import('./typedefs').resolver.CSN} CSN */
+/** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
+/** @typedef {import('./typedefs').resolver.EnumCSN} EnumCSN */
 
 const defaults = {
     // FIXME: add defaults for remaining parameters
@@ -36,12 +40,12 @@ class Visitor {
      * @returns {File[]} a full list of files to be written
      */
     getWriteoutFiles() {
-        return this.fileRepository.getFiles().concat(this.resolver.getUsedLibraries())
+        return [...this.fileRepository.getFiles(), ...this.resolver.getUsedLibraries()]
     }
 
     /**
      * @param {{xtended: CSN, inferred: CSN}} csn - root CSN
-     * @param {VisitorOptions} options - the options
+     * @param {VisitorOptions | {}} options - the options
      */
     constructor(csn, options = {}) {
         amendCSN(csn.xtended)
@@ -124,6 +128,34 @@ class Visitor {
         })
     }
 
+    /**
+     * @param {EntityCSN} entity - the entity to print the actions for
+     * @param {Buffer} buffer - the buffer to write the actions into
+     * @param {import('./typedefs').resolver.EntityInfo[]} ancestors - the fully qualified names of the ancestors of the entity
+     * @param {SourceFile} file - the file the entity is being printed into
+     */
+    #printStaticActions(entity, buffer, ancestors, file) {
+        // TODO: refactor away! All these printing functionalities need to go
+        const actions = Object.entries(entity.actions ?? {})
+        const inherited = ancestors.length
+            ? ancestors.map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.actions`).join(' & ') + ' & '
+            : ''
+        if (actions.length) {
+            buffer.addIndentedBlock(`declare static readonly actions: ${inherited}{`,
+                actions.map(([aname, action]) => SourceFile.stringifyLambda({
+                    name: aname,
+                    parameters: this.#stringifyFunctionParams(action.params, file),
+                    returns: action.returns
+                        ? this.resolver.resolveAndRequire(action.returns, file).typeName
+                        : 'any',
+                    kind: action.kind
+                })), '}'
+            ) // end of actions
+        } else {
+            buffer.add(`declare static readonly actions: ${inherited}${empty}`)
+        }
+    }
+
     /**
      * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
      * That is, for an element A we get:
@@ -131,42 +163,66 @@ class Visitor {
      * - 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 {CSN} entity - the pointer into the CSN to extract the elements from
+     * @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 = {}) {
         const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve entity ${fq}`)
         const clean = options?.cleanName ?? info.withoutNamespace
         const { namespace } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
-        const identSingular = name => name
+        const identSingular = (/** @type {string} */name) => name  // FIXME: remove
+        //const identAspect = name => `_${name}Aspect`
+        /** @param {string} name - the name */
         const identAspect = name => `_${name}Aspect`
-        const toAspectIdent = (wrapped, [ns, n, fq]) => {
+        /**
+         * @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 refersToType = isType(this.csn.inferred.definitions[fq])
-            const ident = identAspect(refersToType 
-                ? n 
-                : this.resolver.inflect({csn: this.csn.inferred.definitions[fq], plainName: n}).singular
-            )
+            const csn = this.csn.inferred.definitions[fq]
+            const ident = isType(csn)
+                ? clean
+                : this.resolver.inflect({csn, plainName: clean}).singular
             return !ns || ns.isCwd(file.path.asDirectory())
-                ? `${ident}(${wrapped})`
-                : `${ns.asIdentifier()}.${ident}(${wrapped})` 
+                ? ident
+                : `${ns.asIdentifier()}.${ident}`
         }
-        const ancestors = (entity.includes ?? [])
-            .map(parent => {
-                const { namespace, entityName } = this.entityRepository.getByFq(parent)
-                file.addImport(namespace)
-                return [namespace, entityName, parent]
+        // remove the ancestry of projections/ views.
+        // They explicitly define their properties.
+        // But at the same time they also carry their .includes clause, which can
+        // clash when the user aliases a selected property with the name of
+        // a properties of the entities they project on:
+        // entity foo as SELECT bar.baz AS ID FROM bar
+        // will produce an error if bar also has a property ID which now clashes with foo.ID
+        // WARNING: annotations from entities without properties should actually be propagated this way!
+        // So once we start caring about annotations, we have to revisit this part.
+        /** @type {import('./typedefs').resolver.EntityInfo[]} */
+        const ancestorInfos = ((!isViewOrProjection(entity) ? entity.includes : []) ?? [])
+            .map(ancestor => {
+                const info = this.entityRepository.getByFq(ancestor)
+                if (!info) throw new Error(`could not resolve ancestor ${ancestor} for ${fq}`)
+                file.addImport(info.namespace)
+                return info
             })
+
+        const ancestorsAspects = ancestorInfos
             .reverse() // reverse so that own aspect A is applied before extensions B,C: B(C(A(Entity)))
-            .reduce(toAspectIdent, 'Base')
+            .reduce((wrapped, ancestor) => `${asIdentifier({info: ancestor, wrapper: name => `_${name}Aspect`, relative: file.path})}(${wrapped})`, 'Base')
 
         this.contexts.push({ entity: fq })
 
         // CLASS ASPECT
         buffer.addIndentedBlock(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`, () => {
-            buffer.addIndentedBlock(`return class ${clean} extends ${ancestors} {`, () => {
+            buffer.addIndentedBlock(`return class ${clean} extends ${ancestorsAspects} {`, () => {
+                /** @type {import('./typedefs').resolver.EnumCSN[]} */
                 const enums = []
                 for (let [ename, element] of Object.entries(entity.elements ?? {})) {
                     if (element.target && /\.texts?/.test(element.target)) {
@@ -176,14 +232,14 @@ class Visitor {
                     this.visitElement(ename, element, file, buffer)
 
                     // make foreign keys explicit
-                    if ('target' in element) {
+                    if (element.target) {
                         // lookup in cds.definitions can fail for inline structs.
                         // We don't really have to care for this case, as keys from such structs are _not_ propagated to
                         // the containing entity.
                         for (const [kname, originalKeyElement] of this.#keys(element.target)) {
                             if (getMaxCardinality(element) === 1 && typeof element.on !== 'object') {  // FIXME: kelement?
                                 const foreignKey = `${ename}_${kname}`
-                                if (Object.hasOwn(entity.elements, foreignKey)) {
+                                if (entity.elements && Object.hasOwn(entity.elements, foreignKey)) {
                                     LOG.error(`Attempting to generate a foreign key reference called '${foreignKey}' in type definition for entity ${fq}. But a property of that name is already defined explicitly. Consider renaming that property.`)
                                 } else {
                                     const kelement = Object.assign(Object.create(originalKeyElement), {
@@ -206,37 +262,39 @@ class Visitor {
                         buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
                         file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}))
                     }
-                    const actions = Object.entries(entity.actions ?? {})
-                    if (actions.length) {
-                        buffer.addIndentedBlock('static readonly actions: {',
-                            actions.map(([aname, action]) => SourceFile.stringifyLambda({
-                                name: aname,
-                                parameters: this.#stringifyFunctionParams(action.params, file),
-                                returns: action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any',
-                                kind: action.kind
-                            }))
-                            , '}') // end of actions
-                    } else {
-                        buffer.add(`static readonly actions: ${empty}`)
-                    }
+                    this.#printStaticActions(entity, buffer, ancestorInfos, file)
                 })
             }, '};') // end of generated class
         }, '}') // end of aspect
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
-        buffer.add(`export class ${identSingular(clean)} extends ${toAspectIdent(`${baseDefinitions.path.asIdentifier()}.Entity`, [undefined, clean, fq])} {${this.#staticClassContents(clean, entity).join('\n')}}`)
+        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(clean, entity).join('\n')}}`)
         this.contexts.pop()
     }
 
+    /**
+     * @param {string} clean - the clean name of the entity
+     * @param {EntityCSN} entity - the entity to generate the static contents for
+     */
     #staticClassContents(clean, entity) {
         return isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : []
     }
 
+    /**
+     * @param {string} fq - fully qualified name of the entity
+     * @param {EntityCSN} entity - the entity to print
+     */
     #printEntity(fq, entity) {
         // static .name has to be defined more forcefully: https://github.com/microsoft/TypeScript/issues/442
+        /**
+         * @param {string} clazz - the class to override the name property for
+         * @param {string} content - the content to set the name property to
+         */
         const overrideNameProperty = (clazz, content) => `Object.defineProperty(${clazz}, 'name', { value: '${content}' })`
-        const { namespace: ns, entityName: clean, inflection } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve entity ${fq}`)
+        const { namespace: ns, entityName: clean, inflection } = info
         const file = this.fileRepository.getNamespaceFile(ns)
         let { singular, plural } = inflection
 
@@ -309,15 +367,15 @@ class Visitor {
      * Stringifies function parameters in preparation of passing them to {@link SourceFile.stringifyLambda}.
      * Resolves all parameters to a pair of parameter name and name of the resolved type.
      * Also filters out parameters that indicate a binding parameter ({@link https://cap.cloud.sap/docs/releases/jan23#simplified-syntax-for-binding-parameters}).
-     * @param {[string, object][]} params - parameter list as found in CSN.
-     * @param {File} file - source file relative to which the parameter types should be resolved.
+     * @param {{[key:string]: EntityCSN}} params - parameter list as found in CSN.
+     * @param {SourceFile} file - source file relative to which the parameter types should be resolved.
      * @returns {[string, string][]} pair of names and types.
      */
     #stringifyFunctionParams(params, file) {
         return params
             ? Object.entries(params)
                 // filter params of type '[many] $self', as they are not to be part of the implementation
-                .filter(([, type]) => type?.type !== '$self' && !(type.items?.type === '$self'))
+                .filter(([, type]) => type?.type !== '$self' && type.items?.type !== '$self')
                 .map(([name, type]) => [
                     name,
                     this.#stringifyFunctionParamType(type, file)
@@ -325,56 +383,80 @@ class Visitor {
             : []
     }
 
+    /**
+     * @param {EntityCSN | EnumCSN} type - type
+     * @param {SourceFile} file - the file to resolve types into
+     */
     #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
-        if (type.enum && this.resolver.builtinResolver.resolveBuiltin(type.type)) return stringifyEnumType(csnToEnumPairs(type))
+        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.typeInfo.isArray || paramType.typeInfo.isDeepRequire
+                ? paramType.typeName
+                : paramType.typeInfo.inflection.singular
         )
     }
 
     /**
      * @param {string} fq - fully qualified name of the operation
-     * @param {object} operation - CSN
+     * @param {import('./typedefs').resolver.OperationCSN} operation - CSN
      * @param {'function' | 'action'} kind - kind of operation
      */
     #printOperation(fq, operation, kind) {
         LOG.debug(`Printing operation ${fq}:\n${JSON.stringify(operation, null, 2)}`)
-        const { namespace } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve operation ${fq}`)
+        const { namespace } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
         const params = this.#stringifyFunctionParams(operation.params, file)
         const returnType = operation.returns
             ? this.resolver.resolveAndRequire(operation.returns, file)
-            : { typeName: 'void', typeInfo: { isArray: false, inflection: { singular: 'void', plural: 'void' } } }
+            : { typeName: 'void', typeInfo: { plainName: 'void', isArray: false, inflection: { singular: 'void', plural: 'void' } } }
         const returns = this.inlineDeclarationResolver.getPropertyDatatype(
             returnType,
-            returnType.typeInfo.isArray ? returnType.typeName : returnType.typeInfo.inflection.singular
+            returnType.typeInfo.isArray
+                ? returnType.typeName
+                : returnType.typeInfo.inflection.singular
         )
         file.addOperation(last(fq), params, returns, kind)
     }
 
+    /**
+     * @param {string} fq - fully qualified name of the type
+     * @param {EntityCSN} type - CSN
+     */
     #printType(fq, type) {
         LOG.debug(`Printing type ${fq}:\n${JSON.stringify(type, null, 2)}`)
-        const { namespace, entityName } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve type ${fq}`)
+        const { namespace, entityName } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
         // 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 ('enum' in type && !isReferenceType(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)) {
+        if (isEnum(type) && !isReferenceType(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)) {
             file.addEnum(fq, entityName, csnToEnumPairs(type))
         } else {
+            const isEnumReference = typeof type.type === 'string' && isEnum(this.csn.inferred.definitions[type?.type])
             // alias
-            file.addType(fq, entityName, this.resolver.resolveAndRequire(type, file).typeName)
+            file.addType(fq, entityName, this.resolver.resolveAndRequire(type, file).typeName, isEnumReference)
         }
         // TODO: annotations not handled yet
     }
 
+    /**
+     * @param {string} fq - fully qualified name of the aspect
+     * @param {EntityCSN} aspect - CSN
+     */
     #printAspect(fq, aspect) {
         LOG.debug(`Printing aspect ${fq}`)
-        const { namespace, entityName, inflection } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve aspect ${fq}`)
+        const { namespace, entityName, inflection } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
         // aspects are technically classes and can therefore be added to the list of defined classes.
         // Still, when using them as mixins for a class, they need to already be defined.
@@ -384,9 +466,15 @@ class Visitor {
         this.#aspectify(fq, aspect, file.aspects, { cleanName: inflection.singular })
     }
 
+    /**
+     * @param {string} fq - fully qualified name of the event
+     * @param {EntityCSN} event - CSN
+     */
     #printEvent(fq, event) {
         LOG.debug(`Printing event ${fq}`)
-        const { namespace, entityName } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve event ${fq}`)
+        const { namespace, entityName } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
         file.addEvent(entityName, fq)
         const buffer = file.events.buffer
@@ -402,9 +490,15 @@ class Visitor {
         }, '}')
     }
 
+    /**
+     * @param {string} fq - fully qualified name of the service
+     * @param {EntityCSN} service - CSN
+     */
     #printService(fq, service) {
         LOG.debug(`Printing service ${fq}:\n${JSON.stringify(service, null, 2)}`)
-        const { namespace } = this.entityRepository.getByFq(fq)
+        const info = this.entityRepository.getByFq(fq)
+        if (!info) throw new Error(`could not resolve service ${fq}`)
+        const { namespace } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
         // service.name is clean of namespace
         file.services.buffer.add(`export default { name: '${service.name}' }`)
@@ -415,7 +509,7 @@ class Visitor {
      * Visits a single entity from the CSN's definition field.
      * Will call #printEntity or #printAction based on the entity's kind.
      * @param {string} fq - name of the entity, fully qualified as is used in the definition field.
-     * @param {CSN} entity - CSN data belonging to the entity to perform lookups in.
+     * @param {EntityCSN} entity - CSN data belonging to the entity to perform lookups in.
      */
     visitEntity(fq, entity) {
         switch (entity.kind) {
@@ -424,6 +518,7 @@ class Visitor {
             break
         case 'action':
         case 'function':
+            // @ts-expect-error - we know entity is actually an OperationCSN
             this.#printOperation(fq, entity, entity.kind)
             break
         case 'aspect':
@@ -470,16 +565,25 @@ class Visitor {
     /**
      * Visits a single element in an entity.
      * @param {string} name - name of the element
-     * @param {import('./resolution/resolver').CSN} element - CSN data belonging to the the element.
+     * @param {EntityCSN} element - CSN data belonging to the the element.
      * @param {SourceFile} file - the namespace file the surrounding entity is being printed into.
-     * @param {Buffer} buffer - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @param {Buffer} [buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
      * @returns @see InlineDeclarationResolver.visitElement
      */
-    visitElement(name, element, file, buffer) {
-        return this.inlineDeclarationResolver.visitElement(name, element, file, buffer)
+    visitElement(name, element, file, buffer = file.classes) {
+        return this.inlineDeclarationResolver.visitElement({
+            name,
+            element,
+            file,
+            buffer,
+            // we explicitly pass the "declare" modifier here to avoid problems with noImplicitOverride and useDefineForClassFields in strict tsconfigs
+            // but not inside type defs (e.g. parameter types) where this would be a syntax error
+            modifiers: getPropertyModifiers(element)
+        })
     }
 }
 
 module.exports = {
     Visitor
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.24.0",
+  "version": "0.25.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",
@@ -24,7 +24,8 @@
     "doc:clean": "rm -rf ./doc",
     "doc:prepare": "npm run doc:clean && mkdir -p doc/types",
     "doc:typegen": "./node_modules/.bin/tsc ./lib/*.js  --skipLibCheck --declaration --allowJs --emitDeclarationOnly --outDir doc/types && cd doc/types && tsc --init",
-    "doc:cli": "npm run cli -- --help > ./doc/cli.txt"
+    "doc:cli": "npm run cli -- --help > ./doc/cli.txt",
+    "jsdoc:check": "tsc --noEmit --project jsconfig.json"
   },
   "files": [
     "lib/",
@@ -44,6 +45,7 @@
   },
   "devDependencies": {
     "@stylistic/eslint-plugin-js": "^1.6.3",
+    "@cap-js/cds-types": ">=0.6",
     "acorn": "^8.10.0",
     "eslint": "^9",
     "eslint-plugin-jsdoc": "^48.2.7",