@cap-js/cds-typer 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -4,7 +4,14 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 0.18.0 - TBD
+## Version 0.19.0 - TBD
+
+## Version 0.18.0 - 2024-03-12
+### Added
+- Improved support for projections, including projections on inline definitions, and on views, as well as support for explicit exclusion and selection of properties
+
+### Changed
+- [breaking] CDS `type` definitions will not be inflected. Whatever inflection you define them in will be assumed treated as a singular form and will not receive a plural form anymore
 
 ## Version 0.17.0 - 2024-03-05
 ### Fixed

package/lib/components/resolver.js

@@ -67,6 +67,34 @@ const Builtins = {
 }
 
 class Resolver {
+
+    #caches = {
+        /**
+         * @type {{ [qualifier: string]: string }}
+         */
+        namespaces: {},
+        /**
+         * @type {{ [qualifier: string]: string }}
+         */
+        propertyAccesses: {}
+    }
+
+    /**
+     * @param {string} qualifier
+     * @returns {string?}
+     */
+    #getCachedNamespace (qualifier) {
+        return this.#caches.namespaces[qualifier]
+    }
+
+    /**
+     * @param {string} qualifier
+     * @returns {string?}
+     */
+    #getCachedPropertyAccess (qualifier) {
+        return this.#caches.propertyAccesses[qualifier]
+    }
+
     get csn() { return this.visitor.csn.inferred }
     
     /** @param {Visitor} visitor */
@@ -91,18 +119,18 @@ class Resolver {
      * to end up with both the resolved Path of the namespace,
      * and the clean name of the class.
      * @param {string} fq the fully qualified name of an entity.
-     * @returns {[Path, string]} a tuple, [0] holding the path to the namespace, [1] holding the clean name of the entity.
+     * @returns {[Path, string, string[]]} a tuple, [0] holding the path to the namespace, [1] holding the clean name of the entity, [2] holding chained property accesses
      */
     untangle(fq) {
         const ns = this.resolveNamespace(fq.split('.'))
-        const name = this.trimNamespace(fq)
-        return [new Path(ns.split('.')), name]
+        const name = this.trimNamespace(fq).split('.').at(-1)  // nested entities would return Foo.Bar, so we only take the last part to get the actual entity name
+        return [new Path(ns.split('.')), name, this.findPropertyAccess(name)]
     }
 
     /**
      * Convenience method to shave off the namespace of a fully qualified path.
      * More specifically, only the parts (reading from right to left) that are of
-     * kind "entity" are retained.
+     * kind "entity" or something similar are retained.
      * a.b.c.Foo -> Foo
      * Bar -> Bar
      * sap.cap.Book.text -> Book.text (assuming Book and text are both of kind "entity")
@@ -110,19 +138,15 @@ class Resolver {
      * @returns {string} the entity name without leading namespace.
      */
     trimNamespace(p) {
-        // TODO: we might want to cache this
-        // start on right side, go up while we have an entity at hand
-        // we cant start on left side, as that clashes with undefined entities like "sap"
+        if (this.#getCachedNamespace(p)) return this.#getCachedNamespace(p)
         const parts = p.split('.')
-        if (parts.length <= 1) {
-            return p
-        }
+        if (parts.length <= 1) return p
 
+        // start on right side, go up while we have an entity at hand
+        // we cant start on left side, as that clashes with undefined entities like "sap"
+        const defs = this.csn.definitions
         let qualifier = parts.join('.')
-        while (
-            this.csn.definitions[qualifier] &&
-            ['entity', 'type', 'aspect', 'event'].includes(this.csn.definitions[qualifier].kind)
-        ) {
+        while (defs[qualifier] && ['entity', 'type', 'aspect', 'event'].includes(defs[qualifier].kind)) {
             parts.pop()
             qualifier = parts.join('.')
         }
@@ -130,6 +154,51 @@ class Resolver {
         return qualifier ? p.substring(qualifier.length + 1) : p
     }
 
+    /**
+     * From a fully qualified path, finds the parts that are property accesses.
+     * This are specifically used in CDS' `typeof` syntax, where a property can
+     * refer to another entity's property type.
+     * @example
+     * ```
+     * namespace namespace;
+     * entity Entity {
+     *   x: Composition of { y: Composition of z: { a: Integer }}
+     * }
+     * 
+     * // somewhere else
+     * entity Foo {
+     *   x: namespace.Entity.x.y.z;
+     * }
+     * ```
+     * 
+     * @example 
+     * ```js
+     * findPropertyAccess('namespace') // []
+     * findPropertyAccess('namespace.Entity') // []
+     * findPropertyAccess('namespace.Entity.x') // ['x']
+     * findPropertyAccess('namespace.Entity.x.y.z') // ['x', 'y', 'z']
+     * ```
+     */
+    findPropertyAccess(p) {
+        if (this.#getCachedPropertyAccess(p)) return this.#getCachedPropertyAccess(p)
+        const parts = p.split('.')
+        if (parts.length <= 1) return []
+
+        // start on right side, go up while we have an entity at hand
+        // we cant start on left side, as that clashes with undefined entities like "sap"
+        // sadly we have to use the extended flavour here, as inferred csn contains artificial entities for
+        // this kind of property access
+        const defs = this.visitor.csn.xtended.definitions
+        const properties = []
+        let qualifier = parts.join('.')
+        while (!defs[qualifier] && parts.length) {
+            properties.unshift(parts.pop())
+            qualifier = parts.join('.')
+        }
+
+        return properties
+    }
+
     /**
      * Generates singular and plural inflection for the passed type.
      * Several cases are covered here:
@@ -149,7 +218,7 @@ class Resolver {
         if (typeInfo.csn?.kind === 'type') {
             return { 
                 singular: typeInfo.plainName,
-                plural: typeInfo.plainName,
+                plural: createArrayOf(typeInfo.plainName),
                 typeName: typeInfo.plainName,
             }
         }
@@ -175,14 +244,13 @@ class Resolver {
             plural = createArrayOf(typeName)
         } else {
             // TODO: make sure the resolution still works. Currently, we only cut off the namespace!
-            singular = util.singular4(typeInfo.csn)
-            plural = util.getPluralAnnotation(typeInfo.csn) ? util.plural4(typeInfo.csn) : typeInfo.plainName
+            plural = util.getPluralAnnotation(typeInfo.csn) ?? typeInfo.plainName
+            singular = util.getSingularAnnotation(typeInfo.csn) ?? util.singular4(typeInfo.csn, true) // util.singular4(typeInfo.csn, true)  // can not use `plural` to honor possible @singular annotation
 
             // don't slice off namespace if it isn't part of the inflected name.
             // This happens when the user adds an annotation and singular4 therefore
-            // already returns an identifier without namespace
+            // already returns an identifier without namespace. Plural has ns already sliced off.
             if (namespace && singular.startsWith(namespace)) {
-                // TODO: not totally sure why plural doesn't have to be sliced
                 singular = singular.slice(namespace.length + 1)
             }
 
@@ -192,7 +260,7 @@ class Resolver {
             }
         }
         if (!singular || !plural) {
-            this.logger.error(`Singular ('${singular}') or plural ('${plural}') for '${typeName}' is empty.`)
+            this.visitor.logger.error(`Singular ('${singular}') or plural ('${plural}') for '${typeName}' is empty.`)
         }
 
         return { typeName, singular, plural }
@@ -278,6 +346,13 @@ class Resolver {
             typeInfo.inflection = this.inflect(typeInfo)
         }
 
+        const [,,propertyAccess] = this.untangle(typeName)
+        if (propertyAccess.length) {
+            const element = typeName.slice(0, -propertyAccess.join('.').length - 1)
+            const access = this.visitor.inlineDeclarationResolver.getTypeLookup(propertyAccess)
+            typeName = deepRequire(element) + access            
+        }
+
         // add fallback inflection. Mainly needed for array-of with builtin types.
         // (array-of relies on inflection being present, which is not the case in builtin)
         typeInfo.inflection ??= {
@@ -349,9 +424,7 @@ class Resolver {
     resolveType(element, file) {
         // while resolving inline declarations, it can happen that we land here
         // with an already resolved type. In that case, just return the type we have.
-        if (element && Object.hasOwn(element, 'isBuiltin')) {
-            return element
-        }
+        if (element && Object.hasOwn(element, 'isBuiltin')) return element
 
         const cardinality = this.getMaxCardinality(element)
 

package/lib/csn.js

@@ -14,8 +14,8 @@ class DraftUnroller {
         this.#csn = c
         this.#entities = Object.values(c.definitions)
         this.#projections = this.#entities.reduce((pjs, entity) => {
-            if (entity.projection) {
-                pjs[entity.name] = entity.projection.from.ref[0]
+            if (isProjection(entity)) {
+                pjs[entity.name] = getProjectionTarget(entity)
             }
             return pjs
         }, {})
@@ -234,12 +234,46 @@ function amendCSN(csn) {
  */
 const isView = entity => entity.query && !entity.projection
 
+const isProjection = entity => entity.projection
+
+const getViewTarget = entity => entity.query?.SELECT?.from?.ref?.[0]
+
+const getProjectionTarget = entity => entity.projection?.from?.ref?.[0]
+
+const getProjectionAliases = entity => {
+    const aliases = {}
+    let all = false
+    for (const col of entity?.projection?.columns ?? []) {
+        if (col === '*') {
+            all = true
+        } else if (col.ref) {
+            (aliases[col.ref[0]] ??= []).push(col.as ?? col.ref[0])
+        } else {
+            // TODO: error, casting seems to miss ref...
+        }
+    }
+    return { aliases, all }
+}
+
 const isDraftEnabled = entity => entity['@odata.draft.enabled'] === true
 
+const isType = entity => entity?.kind === 'type'
+
 /**
  * @see isView
  * Unresolved entities have to be looked up from inferred csn.
  */
 const isUnresolved = entity => entity._unresolved === true
 
-module.exports = { amendCSN, isView, isDraftEnabled, isUnresolved, propagateForeignKeys }
+module.exports = { 
+    amendCSN, 
+    isView, 
+    isProjection,
+    isDraftEnabled,
+    isUnresolved,
+    isType,
+    getProjectionTarget,
+    getProjectionAliases,
+    getViewTarget,
+    propagateForeignKeys
+}

package/lib/util.js

@@ -70,7 +70,7 @@ const singular4 = (dn, stripped = false) => {
         n = n.match(last)[0]
     }
     return (
-        getSingularAnnotation(dn) ||
+        getSingularAnnotation(dn) ??
         (/.*species|news$/i.test(n)
             ? n
             : /.*ess$/.test(n)
@@ -102,7 +102,7 @@ const plural4 = (dn, stripped) => {
         n = n.match(last)[0]
     }
     return (
-        getPluralAnnotation(dn) ||
+        getPluralAnnotation(dn) ??
         (/.*analysis|status|species|news$/i.test(n)
             ? n
             : /.*[^aeiou]y$/.test(n)

package/lib/visitor.js

@@ -2,7 +2,7 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled } = require('./csn')
+const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, isType, isProjection } = require('./csn')
 // eslint-disable-next-line no-unused-vars
 const { SourceFile, FileRepository, baseDefinitions, Buffer } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
@@ -93,7 +93,7 @@ class Visitor {
         for (const [name, entity] of Object.entries(this.csn.xtended.definitions)) {
             if (isView(entity)) {
                 this.visitEntity(name, this.csn.inferred.definitions[name])
-            } else if (!isUnresolved(entity)) {
+            } else if (isProjection(entity) || !isUnresolved(entity)) {
                 this.visitEntity(name, entity)
             } else {
                 this.logger.warning(`Skipping unresolved entity: ${name}`)
@@ -149,13 +149,12 @@ class Visitor {
      * @param {string} name the name of the entity
      * @param {CSN} element the pointer into the CSN to extract the elements from
      * @param {Buffer} buffer the buffer to write the resulting definitions into
-     * @param {string?} cleanName the clean name to use. If not passed, it is derived from the passed name instead.
+     * @param {{cleanName?: string}} options
      */
-    #aspectify(name, entity, buffer, cleanName = undefined) {
-        const clean = cleanName ?? this.resolver.trimNamespace(name)
+    #aspectify(name, entity, buffer, options = {}) {
+        const clean = options?.cleanName ?? this.resolver.trimNamespace(name)
         const ns = this.resolver.resolveNamespace(name.split('.'))
         const file = this.fileRepository.getNamespaceFile(ns)
-
         const identSingular = (name) => name
         const identAspect = (name) => `_${name}Aspect`
 
@@ -165,9 +164,11 @@ class Visitor {
         buffer.addIndentedBlock(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`, function () {
             buffer.addIndentedBlock(`return class ${clean} extends Base {`, function () {
                 const enums = []
-                const exclusions = new Set(entity.projection?.excluding ?? [])
-                const elements = Object.entries(entity.elements ?? {}).filter(([ename]) => !exclusions.has(ename))
-                for (const [ename, element] of elements) {
+                for (let [ename, element] of Object.entries(entity.elements ?? {})) {
+                    if (element.target && /\.texts?/.test(element.target)) {
+                        this.logger.warning(`referring to .texts property in ${name}. This is currently not supported and will be ignored.`)
+                        continue
+                    }
                     this.visitElement(ename, element, file, buffer)
 
                     // make foreign keys explicit
@@ -241,24 +242,30 @@ class Visitor {
     #printEntity(name, entity) {
         // static .name has to be defined more forcefully: https://github.com/microsoft/TypeScript/issues/442
         const overrideNameProperty = (clazz, content) => `Object.defineProperty(${clazz}, 'name', { value: '${content}' })`
-        const clean = this.resolver.trimNamespace(name)
-        const ns = this.resolver.resolveNamespace(name.split('.'))
+        const [ns, clean] = this.resolver.untangle(name)
         const file = this.fileRepository.getNamespaceFile(ns)
         // entities are expected to be in plural anyway, so we would favour the regular name.
         // If the user decides to pass a @plural annotation, that gets precedence over the regular name.
+        
+        /*
         let plural = this.resolver.trimNamespace(util.getPluralAnnotation(entity) ? util.plural4(entity, false) : name)
         const singular = this.resolver.trimNamespace(util.singular4(entity, true))
+        */
+       let { singular, plural } = this.resolver.inflect({csn: entity, plainName: clean}, ns.asNamespace())
+
         // 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.
         // FIXME: put this in a util function
-        if (singular.split('.').at(-1) === plural.split('.').at(-1)) {
-            plural += '_'
+        //if (singular.split('.').at(-1) === plural.split('.').at(-1)) {
+        if (plural.split('.').at(-1) === `${singular.split('.').at(-1)}_`) {
+            //plural += '_'
             this.logger.warning(
                 `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.`
             )
         }
-        if (singular in this.csn.xtended.definitions) {
+        // as types are not inflected, their singular will always clash and there is also no plural for them anyway
+        if (!isType(entity) && singular in this.csn.xtended.definitions) {
             this.logger.error(
                 `Derived singular '${singular}' for your entity '${name}', 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.`
             )
@@ -278,22 +285,33 @@ class Visitor {
         // which would not be possible while already in singular form, as "Book.text" could not be resolved in CSN.
         // edge case: @singular annotation present. singular4 will take care of that.
         file.addInflection(util.singular4(entity, true), plural, clean)
-        if ('doc' in entity) {
-            docify(entity.doc).forEach((d) => buffer.add(d))
-        }
+        docify(entity.doc).forEach(d => buffer.add(d))
 
-        this.#aspectify(name, entity, buffer, singular)
+        // in case of projections `entity` is empty -> retrieve from inferred csn where the actual properties are rolled out
+        const target = isProjection(entity) || isView(entity)
+            ? this.csn.inferred.definitions[name]
+            : entity
+        
+        // draft enablement is stored in csn.xtended. Iff we took the entity from csn.inferred, we have to carry the draft-enablement over at this point
+        target['@odata.draft.enabled'] = isDraftEnabled(entity)
+
+        this.#aspectify(name, target, buffer, { cleanName: singular })
+
+        buffer.add(overrideNameProperty(singular, entity.name))
 
         // PLURAL
-        if (plural.includes('.')) {
-            // Foo.text -> namespace Foo { class text { ... }}
-            plural = plural.split('.').pop()
+
+        // types do not receive a plural
+        if (!isType(entity)) {
+            if (plural.includes('.')) {
+                // Foo.text -> namespace Foo { class text { ... }}
+                plural = plural.split('.').at(-1)
+            }
+            // 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.
+            buffer.add(`export class ${plural} extends Array<${singular}> {${this.#staticClassContents(singular, entity).join('\n')}}`)
+            buffer.add(overrideNameProperty(plural, entity.name))
         }
-        // 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.
-        buffer.add(`export class ${plural} extends Array<${singular}> {${this.#staticClassContents(singular, entity).join('\n')}}`)
-        buffer.add(overrideNameProperty(singular, entity.name))
-        buffer.add(overrideNameProperty(plural, entity.name))
         buffer.add('')
     }
 
@@ -370,7 +388,7 @@ class Visitor {
         // So we separate them into another buffer which is printed before the classes.
         file.addClass(clean, name)
         file.aspects.add(`// the following represents the CDS aspect '${clean}'`)
-        this.#aspectify(name, aspect, file.aspects, clean)
+        this.#aspectify(name, aspect, file.aspects, { cleanName: clean })
     }
 
     #printEvent(name, event) {
@@ -423,7 +441,7 @@ class Visitor {
                 // types like inline definitions can be used very similarly to entities.
                 // They can be extended, contain inline enums, etc., so we treat them as entities.
                 const handler = entity.elements ? this.#printEntity : this.#printType
-                handler.bind(this)(name, entity)
+                handler.call(this, name, entity)
                 break
             }
             case 'event':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.17.0",
+  "version": "0.18.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",
@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.23.3",
+    "@stylistic/eslint-plugin-js": "^1.6.3",
     "acorn": "^8.10.0",
     "eslint": "^8.15.0",
     "jest": "^29",
@@ -48,8 +49,7 @@
   },
   "jest": {
     "projects": [
-      "test/unit.jest.config.js",
-      "test/int.jest.config.js"
+      "test/unit.jest.config.js"
     ]
   }
 }