@cap-js/cds-typer 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -4,14 +4,34 @@ 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.15.0 - TBD
+## Version 0.17.0 - TBD
+
+## Version 0.16.0 - 2024-02-01
+### Changed
+- Changed default log level from `NONE` to `ERROR`. See the doc to manually pass in another log level for cds-typer runs
+- Name collisions between automatically generated foreign key fields (`.…_ID`, `.…_code`, etc.) with explicitly named fields will now raise an error
+- Generate CDS types that are actually structured types as if they were entities. This allows the correct representation of mixing aspects and types in CDS inheritance, and also fixes issues with inline enums in such types
+
+### Fixed
+- Externally defined enums can now be used as parameter types in actions
+
+## Version 0.15.0 - 2023-12-21
+### Added
+- Support for [scoped entities](https://cap.cloud.sap/docs/cds/cdl#scoped-names)
+- Support for [delimited identifiers](https://cap.cloud.sap/docs/cds/cdl#delimited-identifiers)
+
+### Fixed
+- Inline enums are now available during runtime as well
+- Inline enums can now be used as action parameter types as well. These enums will not have a runtime representation, but will only assert type safety!
+- Arrays of inline enum values can now be used as action parameters too. But they will only be represented by their enclosing type for now, i.e. `string`, `number`, etc.
+- Foreign keys of projection entities are now propagated as well
 
 ## Version 0.14.0 - 2023-12-13
 ### Added
 - Entities that are database views now also receive typings
 
 ## Version 0.13.0 - 2023-12-06
-### Changes
+### Changed
 - Enums are now generated ecplicitly in the respective _index.js_ files and don't have to extract their values from the model at runtime anymore
 
 ### Added

package/lib/cli.js

@@ -23,7 +23,7 @@ const flags = {
     logLevel: {
         desc: `Minimum log level that is printed.`,
         allowed: Object.keys(Levels),
-        default: Object.keys(Levels).at(-1),
+        default: Levels.ERROR,
     },
     jsConfigPath: {
         desc: `Path to where the jsconfig.json should be written.${EOL}If specified, ${toolName} will create a jsconfig.json file and${EOL}set it up to restrict property usage in types entities to${EOL}existing properties only.`,
@@ -90,7 +90,7 @@ const main = async (args) => {
     compileFromFile(args.positional, {
         // temporary fix until rootDir is faded out
         outputDirectory: [args.named.outputDirectory, args.named.rootDir].find(d => d !== './') ?? './',
-        logLevel: Levels[args.named.logLevel],
+        logLevel: Levels[args.named.logLevel] ?? args.named.logLevel,
         jsConfigPath: args.named.jsConfigPath,
         inlineDeclarations: args.named.inlineDeclarations,
         propertiesOptional: args.named.propertiesOptional === 'true'

package/lib/components/enum.js

@@ -1,3 +1,5 @@
+const { normalise } = require('./identifier')
+
 /**
  * Prints an enum to a buffer. To be precise, it prints
  * a constant object and a type which together form an artificial enum.
@@ -29,19 +31,35 @@ function printEnum(buffer, name, kvs, options = {}) {
     buffer.add('// enum')
     buffer.add(`${opts.export ? 'export ' : ''}const ${name} = {`)
     buffer.indent()
-    const vals = new Set()
     for (const [k, v] of kvs) {
-        buffer.add(`${k}: ${v},`)
-        vals.add(v?.val ?? v)  // in case of wrapped vals we need to unwrap here for the type
+        buffer.add(`${normalise(k)}: ${v},`)
     }
     buffer.outdent()
     buffer.add('} as const;')
-    buffer.add(`${opts.export ? 'export ' : ''}type ${name} = ${[...vals].join(' | ')}`)
+    buffer.add(`${opts.export ? 'export ' : ''}type ${name} = ${stringifyEnumType(kvs)}`)
     buffer.add('')
 }
 
+/**
+ * Stringifies a list of enum key-value pairs into the righthand side of a TS type.
+ * @param {[string, string][]} kvs list of key-value pairs
+ * @returns {string} a stringified type
+ * @example
+ * ```js
+ * ['A', 'B', 'A'] // -> '"A" | "B"'
+ * ```
+ */
+const stringifyEnumType = kvs => [...uniqueValues(kvs)].join(' | ')
+
+/**
+ * Extracts all unique values from a list of enum key-value pairs.
+ * If the value is an object, then the `.val` property is used.
+ * @param {[string, any | {val: any}][]} kvs
+ */
+const uniqueValues = kvs => new Set(kvs.map(([,v]) => v?.val ?? v))  // in case of wrapped vals we need to unwrap here for the type
+
 // in case of strings, wrap in quotes and fallback to key to make sure values are attached for every key
-const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
+const  enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
 
 /**
  * Converts a CSN type describing an enum into a list of kv-pairs.
@@ -104,7 +122,8 @@ const isInlineEnumType = (element, csn) => element.enum && !(element.type in csn
  * @param {string} name
  * @param {[string, string][]} kvs a list of key-value pairs. Values that are falsey are replaced by 
  */
-const stringifyEnumImplementation = (name, kvs) => `module.exports.${name} = { ${kvs.map(([k,v]) => `${k}: ${v}`).join(', ')} }`
+// ??= for inline enums. If there is some static property of that name, we don't want to override it (for example: ".actions"
+const stringifyEnumImplementation = (name, kvs) => `module.exports.${name} ??= { ${kvs.map(([k,v]) => `${normalise(k)}: ${v}`).join(', ')} }`
 
 
 module.exports = {
@@ -112,5 +131,6 @@ module.exports = {
     csnToEnumPairs,
     propertyToInlineEnumName,
     isInlineEnumType,
-    stringifyEnumImplementation
+    stringifyEnumImplementation,
+    stringifyEnumType
 }

package/lib/components/identifier.js

@@ -0,0 +1,15 @@
+const isValidIdent = /^[_$a-zA-Z][$\w]*$/
+
+/**
+ * Normalises an identifier to a valid JavaScript identifier.
+ * I.e. either the identifier itself or a quoted string.
+ * @param {string} ident the identifier to normalise
+ * @returns {string} the normalised identifier
+ */
+const normalise = ident => ident && !isValidIdent.test(ident)
+    ? `"${ident}"`
+    : ident
+
+module.exports = {
+    normalise
+}

package/lib/components/inline.js

@@ -1,4 +1,5 @@
 const { SourceFile, Buffer } = require('../file')
+const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
 
 /**
@@ -8,7 +9,6 @@ const { docify } = require('./wrappers')
  * their resolution mechanism.
  */
 class InlineDeclarationResolver {
-
     /**
      * @param {string} name
      * @param {import('./resolver').TypeResolveInfo} type
@@ -155,7 +155,7 @@ class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
     flatten(prefix, type) {
         return type.typeInfo.structuredType
             ? Object.entries(type.typeInfo.structuredType).map(([k,v]) => this.flatten(`${this.prefix(prefix)}${k}`, v))
-            : [`${prefix}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
+            : [`${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
     }
 
     printInlineType(name, type, buffer) {
@@ -198,7 +198,7 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
         this.printDepth++
         const lineEnding = this.printDepth > 1 ? ',' : statementEnd
         if (type.typeInfo.structuredType) {
-            const prefix = name ? `${name}${this.getPropertyTypeSeparator()}`: ''
+            const prefix = name ? `${normalise(name)}${this.getPropertyTypeSeparator()}`: ''
             buffer.add(`${prefix} {`)
             buffer.indent()
             for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
@@ -207,7 +207,7 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
             buffer.outdent()
             buffer.add(`}${this.getPropertyDatatype(type, '')}${lineEnding}`)
         } else {
-            buffer.add(`${name}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
+            buffer.add(`${normalise(name)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
         }
         this.printDepth--
         return buffer

package/lib/components/resolver.js

@@ -371,13 +371,34 @@ class Resolver {
             result.isInlineDeclaration = true
         } else {
             if (isInlineEnumType(element, this.csn)) {
-                // we use the singular as the initial declaration of these enums takes place
-                // while defining the singular class. Which therefore uses the singular over the plural name.
-                const cleanEntityName = util.singular4(element.parent, true)
-                const enumName = propertyToInlineEnumName(cleanEntityName, element.name)
-                result.type = enumName
-                result.plainName = enumName
-                result.isInlineDeclaration = true
+                // element.parent is only set if the enum is attached to an entity's property.
+                // If it is missing then we are dealing with an inline parameter type of an action.
+                // Edge case: element.parent is set, but no .name property is attached. This happens
+                // for inline enums inside types:
+                // ```cds
+                // type T {
+                //   x : String enum { ... };  // no element.name for x
+                // }
+                // ```
+                // In that case, we currently resolve to the more general type (cds.String, here)
+                if (element.parent?.name) {
+                    result.isInlineDeclaration = true
+                    // we use the singular as the initial declaration of these enums takes place
+                    // while defining the singular class. Which therefore uses the singular over the plural name.
+                    const cleanEntityName = util.singular4(element.parent, true)
+                    const enumName = propertyToInlineEnumName(cleanEntityName, element.name)
+                    result.type = enumName
+                    result.plainName = enumName
+                } else {
+                    // FIXME: this is the case where users have arrays of enums as action parameter type.
+                    // Instead of building the proper type (e.g. `'A' | 'B' | ...`, we are instead building
+                    // the encasing type (e.g. `string` here)
+                    // We should instead aim for a proper type, i.e. 
+                    // this.#resolveInlineDeclarationType(element.enum, result, file)
+                    // or
+                    // stringifyEnumType(csnToEnumPairs(element))
+                    this.#resolveTypeName(element.type, result)
+                }
             } else {
                 this.resolvePotentialReferenceType(element.type, result, file)
             }            

package/lib/csn.js

@@ -240,4 +240,4 @@ const isView = entity => entity.query && !entity.projection
  */
 const isUnresolved = entity => entity._unresolved === true
 
-module.exports = { amendCSN, isView, isUnresolved }
+module.exports = { amendCSN, isView, isUnresolved, propagateForeignKeys }

package/lib/file.js

@@ -3,6 +3,7 @@
 const fs = require('fs').promises
 const { readFileSync } = require('fs')
 const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = require('./components/enum')
+const { normalise } = require('./components/identifier')
 const path = require('path')
 
 const AUTO_GEN_NOTE = "// This is an automatically generated file. Please do not change its contents manually!"
@@ -151,9 +152,9 @@ class SourceFile extends File {
      * ```
      */
     static stringifyLambda({name, parameters=[], returns='any', initialiser, isStatic=false}) {
-        const parameterTypes = parameters.map(([n, t]) => `${n}: ${t}`).join(', ')
+        const parameterTypes = parameters.map(([n, t]) => `${normalise(n)}: ${t}`).join(', ')
         const callableSignature = `(${parameterTypes}): ${returns}`
-        let prefix = name ? `${name}: `: ''
+        let prefix = name ? `${normalise(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
@@ -268,7 +269,7 @@ class SourceFile extends File {
      */
     addInlineEnum(entityCleanName, entityFqName, propertyName, kvs) {
         this.enums.data.push({ 
-            name: entityFqName,
+            name: `${entityCleanName}.${propertyName}`,
             property: propertyName,
             kvs,
             fq: `${entityCleanName}.${propertyName}`
@@ -375,11 +376,11 @@ class SourceFile extends File {
             this.types.join(),
             this.enums.buffer.join(), 
             this.inlineEnums.buffer.join(), // needs to be before classes
-            namespaces.join(),
             this.aspects.join(), // needs to be before classes
             this.classes.join(),
             this.events.buffer.join(),
-            this.actions.buffer.join()            
+            this.actions.buffer.join(),
+            namespaces.join()  // needs to be after classes for possible declaration merging
         ].filter(Boolean).join('\n')
     }
 

package/lib/util.js

@@ -51,6 +51,7 @@ const getPluralAnnotation = (csn) => csn[annotations.plural.find(a => Object.has
   * unlocalize("{i18n>Foo}") -> "Foo"
   * @param {string} name the entity name (singular or plural).
   * @returns {string} the name without localisation syntax or untouched.
+  * @deprecated we have dropped this feature altogether, users specify custom names via @singular/@plural now
   */
 const unlocalize = (name) => {
 	const match = name.match(/\{i18n>(.*)\}/)

package/lib/visitor.js

@@ -2,14 +2,14 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved } = require('./csn')
+const { amendCSN, isView, isUnresolved, propagateForeignKeys } = require('./csn')
 // eslint-disable-next-line no-unused-vars
 const { SourceFile, baseDefinitions, Buffer } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./components/resolver')
 const { Logger } = require('./logging')
 const { docify } = require('./components/wrappers')
-const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType } = require('./components/enum')
+const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 
  /** @typedef {import('./file').File} File */
  /** @typedef {{ entity: String }} Context */
@@ -63,6 +63,7 @@ class Visitor {
      */
     constructor(csn, options = {}, logger = new Logger()) {
         amendCSN(csn.xtended)
+        propagateForeignKeys(csn.inferred)
         this.options = { ...defaults, ...options }
         this.logger = logger
         this.csn = csn
@@ -130,6 +131,24 @@ class Visitor {
         }
     }
 
+    /**
+     * Retrieves all the keys from an entity.
+     * That is: all keys that are present in both inferred, as well as xtended flavour.
+     * @returns {[string, object][]} array of key name and key element pairs
+     */
+    #keys(name) {
+        // FIXME: this is actually pretty bad, as not only have to propagate keys through
+        // both flavours of CSN (see constructor), but we are now also collecting them from
+        // both flavours and deduplicating them.
+        // xtended contains keys that have been inherited from parents
+        // inferred contains keys from queried entities (thing `entity Foo as select from Bar`, where Bar has keys)
+        // So we currently need them both.
+        return Object.entries({
+            ...this.csn.inferred.definitions[name]?.keys ?? {},
+            ...this.csn.xtended.definitions[name]?.keys ?? {}
+        })
+    }
+
     /**
      * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
      * That is, for an element A we get:
@@ -168,10 +187,15 @@ class Visitor {
                 // 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, kelement] of Object.entries(this.csn.xtended.definitions[element.target]?.keys ?? {})) {
+                for (const [kname, kelement] of this.#keys(element.target)) {
                     if (this.resolver.getMaxCardinality(element) === 1) {
-                        kelement.isRefNotNull = !!element.notNull || !!element.key
-                        this.visitElement(`${ename}_${kname}`, kelement, file, buffer)
+                        const foreignKey = `${ename}_${kname}`
+                        if (Object.hasOwn(entity.elements, foreignKey)) {
+                            this.logger.error(`Attempting to generate a foreign key reference called '${foreignKey}' in type definition for entity ${name}. But a property of that name is already defined explicitly. Consider renaming that property.`)
+                        } else {
+                            kelement.isRefNotNull = !!element.notNull || !!element.key
+                            this.visitElement(foreignKey, kelement, file, buffer)
+                        }
                     }
                 }
             }
@@ -247,11 +271,13 @@ class Visitor {
         const file = this.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 = util.unlocalize(
-            this.resolver.trimNamespace(util.getPluralAnnotation(entity) ? util.plural4(entity, false) : name)
-        )
-        const singular = util.unlocalize(util.singular4(entity, true))
-        if (singular === plural) {
+        let plural = this.resolver.trimNamespace(util.getPluralAnnotation(entity) ? util.plural4(entity, false) : name)
+        const singular = this.resolver.trimNamespace(util.singular4(entity, true))
+        // 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 += '_'
             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.`
@@ -259,7 +285,7 @@ class Visitor {
         }
         if (singular in this.csn.xtended.definitions) {
             this.logger.error(
-                `Derived singular '${singular}' for your entity '${name}', already exists. The resulting types will be erronous. Please consider using '@singular:'/ '@plural:' annotations in your model to resolve this collision.`
+                `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.`
             )
         }
         file.addClass(singular, name)
@@ -281,7 +307,7 @@ class Visitor {
             docify(entity.doc).forEach((d) => buffer.add(d))
         }
 
-        this.#aspectify(name, entity, file.classes, singular)
+        this.#aspectify(name, entity, buffer, singular)
 
         // PLURAL
         if (plural.includes('.')) {
@@ -311,11 +337,19 @@ class Visitor {
                 .filter(([, type]) => type?.type !== '$self' && !(type.items?.type === '$self'))
                 .map(([name, type]) => [
                     name,
-                    this.resolver.visitor.inlineDeclarationResolver.getPropertyDatatype(this.resolver.resolveAndRequire(type, file)),
+                    this.#stringifyFunctionParamType(type, file)
                 ])
             : []
     }
 
+    #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
+        return type.enum && type.type.startsWith('cds.')
+            ? stringifyEnumType(csnToEnumPairs(type))
+            : this.inlineDeclarationResolver.getPropertyDatatype(this.resolver.resolveAndRequire(type, file))
+    }
+
     #printFunction(name, func) {
         // FIXME: mostly duplicate of printAction -> reuse
         this.logger.debug(`Printing function ${name}:\n${JSON.stringify(func, null, 2)}`)
@@ -412,12 +446,16 @@ class Visitor {
             case 'function':
                 this.#printAction(name, entity)
                 break
-            case 'type':
-                this.#printType(name, entity)
-                break
             case 'aspect':
                 this.#printAspect(name, entity)
                 break
+            case 'type': {
+                // 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)
+                break
+            }
             case 'event':
                 this.#printEvent(name, entity)
                 break
@@ -425,7 +463,7 @@ class Visitor {
                 this.#printService(name, entity)
                 break
             default:
-                this.logger.error(`Unhandled entity kind '${entity.kind}'.`)
+                this.logger.debug(`Unhandled entity kind '${entity.kind}'.`)
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.14.0",
+  "version": "0.16.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",