@cap-js/cds-typer 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -4,10 +4,25 @@ 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.14.0 - TBD
+## Version 0.16.0 - TBD
+
+## 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/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,17 +31,33 @@ 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
 
@@ -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,26 @@ 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.
+                if (element.parent) {
+                    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

@@ -226,4 +226,18 @@ function amendCSN(csn) {
     propagateForeignKeys(csn)
 }
 
-module.exports = { amendCSN }
+/**
+ * FIXME: this is pretty handwavey: we are looking for view-entities,
+ * i.e. ones that have a query, but are not a cds level projection.
+ * Those are still not expanded and we have to retrieve their definition
+ * with all properties from the inferred model.
+ */
+const isView = entity => entity.query && !entity.projection
+
+/**
+ * @see isView
+ * Unresolved entities have to be looked up from inferred csn.
+ */
+const isUnresolved = entity => entity._unresolved === true
+
+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 } = 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
@@ -99,10 +100,12 @@ class Visitor {
      */
     visitDefinitions() {
         for (const [name, entity] of Object.entries(this.csn.xtended.definitions)) {
-            if (entity._unresolved === true) {
-                this.logger.error(`Skipping unresolved entity: ${JSON.stringify(entity)}`)
-            } else {
+            if (isView(entity)) {
+                this.visitEntity(name, this.csn.inferred.definitions[name])
+            } else if (!isUnresolved(entity)) {
                 this.visitEntity(name, entity)
+            } else {
+                this.logger.warning(`Skipping unresolved entity: ${name}`)
             }
         }
         // FIXME: optimise
@@ -128,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:
@@ -166,7 +187,7 @@ 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)
@@ -245,11 +266,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.`
@@ -279,7 +302,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('.')) {
@@ -309,11 +332,17 @@ 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) {
+        return type.enum
+            ? 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)}`)

package/package.json

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