@cap-js/cds-typer 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -4,13 +4,35 @@ 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.24.0 - TBD
+## Version 0.26.0 - TBD
+
+## Version 0.25.0 - 2024-08-13
+### Added
+- Declaring a type alias on an enum in cds now also exports it on value level in the resulting type
+
+### Fixed
+- Classes representing views and projections will no longer carry ancestry to avoid clashes thereof with aliases fields
+
+### Changed
+- All properties are now preceeded with the `declare` modifier to pass strict tsconfigs using `useDefineForClassFields` or `noImplicitOverride`
+- The static `actions` property of generated classes now includes the types from all inherited classes to also suggest actions defined in a base entity/aspect/type.
+
+## Version 0.24.0 - 2024-07-18
+### Fixed
+- Suppressed an error that would incorrectly point out naming clashes when an entity was named in singular inflection in the model
+- CDS aspects now also generate a aspect-function in singular inflection, similar to how entities do
+
+### Changed
+- Aspects generate named classes again so that tooltips will show more meaningful provenance for properties
+- The TypeScript task for `cds build` no longer looks for tsconfig.json to determine if the project has TS nature and instead checks the dependencies in the project's package.json for an occurrence of `typescript`
 
 ## Version 0.23.0 - 2024-07-04
+
 ### Fixed
 - Plurals no longer have `is_singular` attached in the resulting .js files
 - Properties are properly propagated beyond just one level of inheritance
 
+
 ## Version 0.22.0 - 2024-06-20
 ### Fixed
 - Fixed a bug where keys would sometimes inconsistently become nullable

package/cds-plugin.js

@@ -10,9 +10,14 @@ const DEBUG = cds.debug('cli|build')
 const BUILD_CONFIG = 'tsconfig.cdsbuild.json'
 
 /**
- * Check if a tsconfig file exists.
+ * Check if the project is a TypeScript project by looking for a dependency on TypeScript.
+ * @returns {boolean}
  */
-const tsConfigExists = () => fs.existsSync('tsconfig.json')
+const isTypeScriptProject = () => {
+    if (!fs.existsSync('package.json')) return false
+    const pkg = require(path.resolve('package.json'))
+    return Boolean(pkg.devDependencies?.typescript || pkg.dependencies?.typescript)
+}
 
 /**
  * Check if separate tsconfig file that is used for building the project.
@@ -56,7 +61,7 @@ if (!cds?.version || cds.version < '8.0.0') {
 // requires @sap/cds-dk version >= 7.5.0
 cds.build?.register?.('typescript', class extends cds.build.Plugin {
     static taskDefaults = { src: '.' }
-    static hasTask() { return tsConfigExists() }
+    static hasTask() { return isTypeScriptProject() }
 
     // lower priority than the nodejs task
     get priority() { return -1 }

package/lib/cli.js

@@ -12,6 +12,9 @@ const { EOL } = require('node:os')
 const EOL2 = EOL + EOL
 const toolName = 'cds-typer'
 
+// @ts-expect-error - nope, it is actually there. Types just seem to be out of sync.
+const lls = cds.log.levels
+
 const flags = {
     outputDirectory: {
         desc: 'Root directory to write the generated files to.',
@@ -23,10 +26,10 @@ const flags = {
     },
     logLevel: {
         desc: `Minimum log level that is printed.${EOL}The default is only used if no explicit value is passed${EOL}and there is no configuration passed via cds.env either.`,
-        allowed: Object.keys(cds.log.levels).concat(Object.keys(deprecated)),
-        allowedHint: Object.keys(cds.log.levels).join(' | '),  // FIXME: remove once old levels are faded out
-        defaultHint: _keyFor(cds.log.levels.ERROR),
-        default: cds?.env?.log?.levels?.['cds-typer'] ?? _keyFor(cds.log.levels.ERROR),
+        allowed: Object.keys(lls).concat(Object.keys(deprecated)),
+        allowedHint: Object.keys(lls).join(' | '),  // FIXME: remove once old levels are faded out
+        defaultHint: _keyFor(lls.ERROR),
+        default: cds?.env?.log?.levels?.['cds-typer'] ?? _keyFor(lls.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.`,
@@ -53,25 +56,32 @@ const flags = {
 }
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'
-const indent = (s, indentation) => s.split(EOL).map(line => `${indentation}${line}`).join(EOL)
+/**
+ * @param {string} s - the string to indent
+ * @param {string} indentation - the indentation to use
+ */
+const indent = (s, indentation) => s
+    .split(EOL)
+    .map((/** @type {string} */ line) => `${indentation}${line}`)
+    .join(EOL)
 
 const help = () => `SYNOPSIS${EOL2}` +
         indent('cds-typer [cds file | "*"]', '  ') + EOL2 +
         indent(`Generates type information based on a CDS model.${EOL}Call with at least one positional parameter pointing${EOL}to the (root) CDS file you want to compile.`, '  ') + EOL2 +
             `OPTIONS${EOL2}` +
             Object.entries(flags)
-                .sort()
+                .sort(([a], [b]) => a.localeCompare(b))
                 .map(([key, value]) => {
                     let s = indent(`--${key}`, '  ')
-                    if (value.allowedHint) {
-                        s += ` ${value.allowedHint}`
-                    } else if (value.allowed) {
-                        s += `: <${value.allowed.join(' | ')}>`
-                    } else if (value.type) {
-                        s += `: <${value.type}>`
-                    }
+                    // @ts-expect-error - not going to check presence of each property. Same for the following expect-errors.
+                    if (value.allowedHint) s += ` ${value.allowedHint}`
+                    // @ts-expect-error
+                    else if (value.allowed) s += `: <${value.allowed.join(' | ')}>`
+                    else if ('type' in value && value.type) s += `: <${value.type}>`
+                    // @ts-expect-error
                     if (value.defaultHint || value.default) {
                         s += EOL
+                        // @ts-expect-error
                         s += indent(`(default: ${value.defaultHint ?? value.default})`, '    ')
                     }
                     s += `${EOL2}${indent(value.desc, '    ')}`
@@ -81,7 +91,7 @@ const help = () => `SYNOPSIS${EOL2}` +
 
 const version = () => require('../package.json').version
 
-const main = async args => {
+const main = async (/** @type {any} */ args) => {
     if ('help' in args.named) {
         console.log(help())
         process.exit(0)

package/lib/compile.js

@@ -26,7 +26,7 @@ const writeJsConfig = path => {
     }
 
     if (fs.existsSync(path)) {
-        const currentContents = JSON.parse(fs.readFileSync(path))
+        const currentContents = JSON.parse(fs.readFileSync(path, 'utf8'))
         if (currentContents?.compilerOptions?.checkJs) {
             LOG.warn(`jsconfig at location ${path} already exists. Attempting to merge.`)
         }
@@ -39,7 +39,7 @@ const writeJsConfig = path => {
 
 /**
  * Compiles a CSN object to Typescript types.
- * @param {{xtended: CSN, inferred: CSN}} csn - csn tuple
+ * @param {{xtended: import('./typedefs').resolver.CSN, inferred: import('./typedefs').resolver.CSN}} csn - csn tuple
  * @param {CompileParameters} parameters - path to root directory for all generated files, min log level
  */
 const compileFromCSN = async (csn, parameters) => {
@@ -57,7 +57,7 @@ const compileFromCSN = async (csn, parameters) => {
 
 /**
  * Compiles a .cds file to Typescript types.
- * @param {string} inputFile - path to input .cds file
+ * @param {string | string[]} inputFile - path to input .cds file
  * @param {CompileParameters} parameters - path to root directory for all generated files, min log level, etc.
  */
 const compileFromFile = async (inputFile, parameters) => {

package/lib/components/enum.js

@@ -19,6 +19,11 @@ const uniqueValues = kvs => new Set(kvs.map(([,v]) => v?.val ?? v))  // in case
 const stringifyEnumType = kvs => [...uniqueValues(kvs)].join(' | ')
 
 // in case of strings, wrap in quotes and fallback to key to make sure values are attached for every key
+/**
+ * @param {string} key - the key of the enum
+ * @param {any} value - the value of the enum
+ * @param {string | import('@sap/cds').ref} enumType - the type of the enum
+ */
 const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
 
 /**
@@ -41,7 +46,7 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
  * const E = { a: 'A', b: 'B' }
  * type E = 'A' | 'B'
  * ```
- * @param {Buffer} buffer - Buffer to write into
+ * @param {import('../file').Buffer} buffer - Buffer to write into
  * @param {string} name - local name of the enum, i.e. the name under which it should be created in the .ts file
  * @param {[string, string][]} kvs - list of key-value pairs
  * @param {object} options - options for printing the enum
@@ -60,12 +65,13 @@ function printEnum(buffer, name, kvs, options = {}) {
  * Converts a CSN type describing an enum into a list of kv-pairs.
  * Values from CSN are unwrapped from their `.val` structure and
  * will fall back to the key if no value is provided.
- * @param {{enum: {[key: name]: string}, type: string}} enumCsn - the CSN type describing the enum
- * @param {{unwrapVals: boolean}} options - if `unwrapVals` is passed,
+ * @param {import('../typedefs').resolver.EnumCSN} enumCsn - the CSN type describing the enum
+ * @param {{unwrapVals: boolean} | {}} options - if `unwrapVals` is passed,
  *  then the CSN structure `{val:x}` is flattened to just `x`.
  *  Retaining `val` is closer to the actual CSN structure and should be used where we want
  *  to mimic the runtime as closely as possible (inline enum types).
  *  Stripping that additional wrapper would be more readable for users.
+ * @returns {[string, any][]}
  * @example
  * ```ts
  * const csn = {enum: {X: {val: 'a'}, Y: {val: 'b'}, Z: {}}}
@@ -74,10 +80,10 @@ function printEnum(buffer, name, kvs, options = {}) {
  * ```
  */
 const csnToEnumPairs = ({enum: enm, type}, options = {}) => {
-    options = {...{unwrapVals: true}, ...options}
+    const actualOptions = {...{unwrapVals: true}, ...options}
     return Object.entries(enm).map(([k, v]) => {
         const val = enumVal(k, v.val, type)
-        return [k, (options.unwrapVals ? val : { val })]
+        return [k, (actualOptions.unwrapVals ? val : { val })]
     })
 }
 
@@ -91,11 +97,12 @@ const propertyToInlineEnumName = (entity, property) => `${entity}_${property}`
  * A type is considered to be an inline enum, iff it has a `.enum` property
  * _and_ its type is a CDS primitive, i.e. it is not contained in `cds.definitions`.
  * If it is contained there, then it is a standard enum declaration that has its own name.
- * @param {{type: string}} element - the element to check
- * @param {object} csn - the CSN model
- * @returns boolean
+ * @param {{type: string | import('../typedefs').resolver.ref, [key: string]: any}} element - the element to check
+ * @param {import('../typedefs').resolver.CSN} csn - the CSN model
+ * @returns {element is import('../typedefs').resolver.EnumCSN}
  */
-const isInlineEnumType = (element, csn) => element.enum && !(element.type in csn.definitions)
+const isInlineEnumType = (element, csn) => element.enum
+    && !(typeof element.type === 'string' && element.type in csn.definitions)
 
 /**
  * Stringifies an enum into a runtime artifact.

package/lib/components/identifier.js

@@ -15,7 +15,7 @@ const normalise = ident => ident && !isValidIdent.test(ident)
  * @param {string} ident - the identifier to extract the last part from
  * @returns {string} the last part of the identifier
  */
-const last = ident => ident.split('.').at(-1)
+const last = ident => ident.split('.').at(-1) ?? ident
 
 module.exports = {
     normalise,

package/lib/components/inline.js

@@ -3,6 +3,10 @@ const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
 
 /** @typedef {import('../resolution/resolver').TypeResolveInfo} TypeResolveInfo */
+/** @typedef {import('../typedefs').visitor.Inflection} Inflection */
+/** @typedef {import('../typedefs').resolver.PropertyModifier} PropertyModifier */
+/** @typedef {import('../visitor').Visitor} Visitor */
+/** @typedef {{typeName: string, typeInfo: TypeResolveInfo}} TypeResolveInfo_ */
 
 /**
  * Inline declarations of types can come in different flavours.
@@ -12,15 +16,17 @@ const { docify } = require('./wrappers')
  */
 class InlineDeclarationResolver {
     /**
-     * @param {string} fq - full qualifier of the type
-     * @param {TypeResolveInfo} type - type info so far
-     * @param {import('../file').Buffer} buffer - the buffer to write into
-     * @param {string} statementEnd - statement ending character
+     * @param {object} options - options to be passed to the resolver
+     * @param {string} options.fq - full qualifier of the type
+     * @param {TypeResolveInfo_} options.type - type info so far
+     * @param {import('../file').Buffer} options.buffer - the buffer to write into
+     * @param {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
+     * @param {string} [options.statementEnd] - statement ending character
      * @protected
      * @abstract
      */
     // eslint-disable-next-line no-unused-vars
-    printInlineType(fq, type, buffer, statementEnd) { /* abstract */ }
+    printInlineType({fq, type, buffer, modifiers, statementEnd}) { /* abstract */ }
 
     /**
      * Attempts to resolve a type that could reference another type.
@@ -39,6 +45,8 @@ class InlineDeclarationResolver {
         for (const [subname, subelement] of Object.entries(items ?? {})) {
             // in inline definitions, we sometimes have to resolve first
             // FIXME: does this tie in with how we sometimes end up with resolved typed in resolveType()?
+            // FIXME2: I don't think the if branch is actually called in real world situations.
+            // so we can probably get rid of this distinction and make #resolveTypeName private again
             const se = (typeof subelement === 'string')
                 ? this.visitor.resolver.resolveTypeName(subelement)
                 : subelement
@@ -58,13 +66,15 @@ class InlineDeclarationResolver {
 
     /**
      * 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 {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 {object} options - options
+     * @param {string} options.name - name of the element
+     * @param {import('../typedefs').resolver.EntityCSN} options.element - CSN data belonging to the the element.
+     * @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 {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
      * @public
      */
-    visitElement(name, element, file, buffer = file.classes) {
+    visitElement({name, element, file, buffer = file.classes, modifiers = []}) {
         this.depth++
         for (const d of docify(element.doc)) {
             buffer.add(d)
@@ -72,7 +82,7 @@ class InlineDeclarationResolver {
         const type = this.visitor.resolver.resolveAndRequire(element, file)
         this.depth--
         if (this.depth === 0) {
-            this.printInlineType(name, type, buffer)
+            this.printInlineType({fq: name, type, buffer, modifiers})
         }
         return type
     }
@@ -89,7 +99,7 @@ class InlineDeclarationResolver {
 
     /**
      * It returns TypeScript datatype for provided TS property
-     * @param {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection } }} type - type of the property
+     * @param {TypeResolveInfo_} type - type of the property
      * @param {string} typeName - name of the TypeScript property
      * @returns {string} the datatype to be presented on TypeScript layer
      * @public
@@ -98,7 +108,16 @@ class InlineDeclarationResolver {
         return type.typeInfo.isNotNull ? typeName : `${typeName} | null`
     }
 
-    /** @param {import('../visitor').Visitor} visitor - the visitor */
+    /**
+     * Stringifies additional modifiers for a property
+     * @param {(PropertyModifier)[]} modifiers - modifiers to stringify
+     * @returns {string} the modifiers as a string
+     */
+    stringifyModifiers (modifiers) {
+        return modifiers?.length > 0 ? modifiers.join(' ') + ' ' : ''
+    }
+
+    /** @param {Visitor} visitor - the visitor */
     constructor(visitor) {
         this.visitor = visitor
         // type resolution might recurse. This indicator is used to determine
@@ -148,24 +167,42 @@ class InlineDeclarationResolver {
  * ```
  */
 class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
-    constructor(visitor) { super(visitor) }
-
+    /**
+     * @param {string} p - prefix to use
+     */
     prefix(p) {
         return p ? `${p}_` : ''
     }
 
-    flatten(prefix, type) {
+    /**
+     * @param {object} options - options
+     * @param {string} options.prefix - prefix to use
+     * @param {TypeResolveInfo_} options.type - type to flatten
+     * @param {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
+     * @returns {string[]} the flattened properties
+     */
+    flatten({prefix, type, modifiers}) {
         return type.typeInfo.structuredType
-            ? Object.entries(type.typeInfo.structuredType).map(([k,v]) => this.flatten(`${this.prefix(prefix)}${k}`, v))
-            : [`${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
+            ? Object.entries(type.typeInfo.structuredType).map(
+                ([k,v]) => this.flatten({prefix: `${this.prefix(prefix)}${k}`, type: v, modifiers})  // for flat we pass the modifiers!
+            ).flat()
+            : [`${this.stringifyModifiers(modifiers)}${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
     }
 
-    printInlineType(name, type, buffer) {
-        for(const prop of this.flatten(name, type).flat()) {
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['printInlineType']}
+     */
+    printInlineType({fq, type, buffer, modifiers}) {
+        for(const prop of this.flatten({prefix: fq, type, modifiers}).flat()) {
             buffer.add(prop)
         }
     }
 
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['getTypeLookup']}
+     */
     getTypeLookup(members)  {
         return `['${members.join('_')}']`
     }
@@ -189,39 +226,57 @@ class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
  * ```
  */
 class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
+    /** @param {Visitor} visitor - the visitor */
     constructor(visitor) {
         super(visitor)
         this.printDepth = 0
     }
 
-    flatten(name, type, buffer, statementEnd = ';') {
+    /**
+     * @param {object} options - options
+     * @param {string} options.fq - full qualifier of the type
+     * @param {TypeResolveInfo_} options.type - type info so far
+     * @param {Buffer} options.buffer - the buffer to write into
+     * @param {PropertyModifier[]} [options.modifiers] - modifiers to add to each generated property
+     * @param {string} [options.statementEnd] - statement ending character
+     * FIXME: reuse type
+     */
+    flatten({fq, type, buffer, modifiers = [], statementEnd = ';'}) {
         // in addition to the regular depth during resolution, we may have another depth while printing
         // nested types on which the line ending depends
         this.printDepth++
         const lineEnding = this.printDepth > 1 ? ',' : statementEnd
         if (type.typeInfo.structuredType) {
-            const prefix = name ? `${normalise(name)}${this.getPropertyTypeSeparator()}`: ''
+            const prefix = fq ? `${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()}`: ''
             buffer.add(`${prefix} {`)
             buffer.indent()
             for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
-                this.flatten(n, t, buffer)
+                this.flatten({fq: n, type: t, buffer})
             }
             buffer.outdent()
             buffer.add(`}${this.getPropertyDatatype(type, '')}${lineEnding}`)
         } else {
-            buffer.add(`${normalise(name)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
+            buffer.add(`${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
         }
         this.printDepth--
         return buffer
     }
 
-    printInlineType(name, type, buffer, statementEnd) {
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['printInlineType']}
+     */
+    printInlineType({fq, type, buffer, modifiers, statementEnd}) {
         // FIXME: indent not quite right
         const sub = new Buffer()
         sub.currentIndent = buffer.currentIndent
-        buffer.add(this.flatten(name, type, sub, statementEnd).join())
+        buffer.add(this.flatten({fq, type, buffer: sub, modifiers, statementEnd}).join())
     }
 
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['getTypeLookup']}
+     */
     getTypeLookup(members)  {
         return members.map(m => `['${m}']`).join('')
     }

package/lib/components/property.js

@@ -0,0 +1,12 @@
+/**
+ * Determines the proper modifiers for a property.
+ * For most properties, this will be "declare". But for some properties,
+ * like fields of a type, we don't want any modifiers.
+ * @param {import('../typedefs').resolver.EntityCSN} element - The element to determine the modifiers for.
+ * @returns {import('../typedefs').resolver.PropertyModifier[]} The modifiers for the property.
+ */
+const getPropertyModifiers = element => element?.parent?.kind !== 'type' ? ['declare'] : []
+
+module.exports = {
+    getPropertyModifiers
+}

package/lib/components/wrappers.js

@@ -55,7 +55,7 @@ const deepRequire = (t, lookup = '') => `${base}.DeepRequired<${t}>${lookup}`
 
 /**
  * Puts a passed string in docstring format.
- * @param {string} doc - raw string to docify. May contain linebreaks.
+ * @param {string | undefined} doc - raw string to docify. May contain linebreaks.
  * @returns {string[]} an array of lines wrapped in doc format. The result is not
  *          concatenated to be properly indented by `buffer.add(...)`.
  */