@cap-js/cds-typer 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -4,7 +4,15 @@ 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.22.0 - TBD
+## Version 0.23.0 - TBD
+
+## Version 0.22.0 - 2024-06-20
+### Fixed
+- Fixed a bug where keys would sometimes inconsistently become nullable
+
+## Version 0.21.2 - 2024-06-06
+### Fixed
+- The typescript build task will no longer attempt to run unless at least cds 8 is installed
 
 ## Version 0.21.1 - 2024-06-03
 ### Fixed

package/cds-plugin.js

@@ -21,7 +21,7 @@ const tsConfigExists = () => fs.existsSync('tsconfig.json')
 const buildConfigExists = () => fs.existsSync(BUILD_CONFIG)
 
 /**
- * @param {string} dir The directory to remove.
+ * @param {string} dir - The directory to remove.
  */
 const rmDirIfExists = dir => {
     try { fs.rmSync(dir, { recursive: true }) } catch { /* ignore */ }
@@ -29,8 +29,8 @@ const rmDirIfExists = dir => {
 
 /**
  * Remove files with given extensions from a directory recursively.
- * @param {string} dir The directory to start from.
- * @param {string[]} exts The extensions to remove.
+ * @param {string} dir - The directory to start from.
+ * @param {string[]} exts - The extensions to remove.
  * @returns {Promise<void>}
  */
 const rmFiles = async (dir, exts) => fs.existsSync(dir) 
@@ -47,6 +47,12 @@ const rmFiles = async (dir, exts) => fs.existsSync(dir)
     )
     : undefined
 
+// FIXME: remove once cds7 has been phased out
+if (!cds?.version || cds.version < '8.0.0') {
+    DEBUG?.('typescript build task requires @sap/cds-dk version >= 8.0.0, skipping registration')
+    return
+}
+
 // requires @sap/cds-dk version >= 7.5.0
 cds.build?.register?.('typescript', class extends cds.build.Plugin {
     static taskDefaults = { src: '.' }

package/lib/compile.js

@@ -15,8 +15,8 @@ const { Visitor } = require('./visitor')
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
  * Tries to merge nicely if an existing file is found.
- * @param path {string} filepath to jsconfig.json.
- * @param logger {import('./logging').Logger} logger
+ * @param {string} path - filepath to jsconfig.json.
+ * @param {import('./logging').Logger} logger - logger
  * @private
  */
 const writeJsConfig = (path, logger) => {
@@ -41,7 +41,7 @@ const writeJsConfig = (path, logger) => {
 /**
  * Compiles a CSN object to Typescript types.
  * @param {{xtended: CSN, inferred: CSN}} csn
- * @param parameters {CompileParameters} path to root directory for all generated files, min log level
+ * @param {CompileParameters} parameters - path to root directory for all generated files, min log level
  */
 const compileFromCSN = async (csn, parameters) => {
     const envSettings = cds.env?.typer ?? {}
@@ -59,8 +59,8 @@ const compileFromCSN = async (csn, parameters) => {
 
 /**
  * Compiles a .cds file to Typescript types.
- * @param inputFile {string} path to input .cds file
- * @param parameters {CompileParameters} path to root directory for all generated files, min log level, etc.
+ * @param {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) => {
     const paths = typeof inputFile === 'string' ? normalize(inputFile) : inputFile.map(f => normalize(f))

package/lib/components/enum.js

@@ -9,7 +9,7 @@ const uniqueValues = kvs => new Set(kvs.map(([,v]) => v?.val ?? v))  // in case
 
 /**
  * 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
+ * @param {[string, string][]} kvs - list of key-value pairs
  * @returns {string} a stringified type
  * @example
  * ```js
@@ -29,7 +29,6 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
  * and a type containing all disctinct values.
  * We can get away with this as TS doesn't feature nominal typing, so the structure
  * is all we care about.
- * 
  * @example
  * ```cds
  * type E: enum of String {
@@ -42,10 +41,10 @@ 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 {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 {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
  */
 function printEnum(buffer, name, kvs, options = {}) {
     const opts = {...{export: true}, ...options} 
@@ -61,14 +60,12 @@ 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
- * @param {{unwrapVals: boolean}} options if `unwrapVals` is passed,
+ * @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.
- * 
  * @example
  * ```ts 
  * const csn = {enum: {X: {val: 'a'}, Y: {val: 'b'}, Z: {}}}
@@ -94,7 +91,6 @@ 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
  * @param {object} csn
  * @returns boolean
@@ -116,7 +112,7 @@ const isInlineEnumType = (element, csn) => element.enum && !(element.type in csn
  * module.exports.Language = { DE: "German", EN: "English", FR: "FR" }
  * ```
  * @param {string} name
- * @param {[string, string][]} kvs a list of key-value pairs. Values that are falsey are replaced by 
+ * @param {[string, string][]} kvs - a list of key-value pairs. Values that are falsey are replaced by 
  */
 // ??= 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(', ')} }`

package/lib/components/identifier.js

@@ -3,7 +3,7 @@ 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
+ * @param {string} ident - the identifier to normalise
  * @returns {string} the normalised identifier
  */
 const normalise = ident => ident && !isValidIdent.test(ident)

package/lib/components/inline.js

@@ -23,8 +23,8 @@ class InlineDeclarationResolver {
     /**
      * Attempts to resolve a type that could reference another type.
      * @param {any} items 
-     * @param {import('./resolver').TypeResolveInfo} into @see Visitor.resolveType
-     * @param {SourceFile} file temporary file to resolve dummy types into.
+     * @param {import('./resolver').TypeResolveInfo} into - @see Visitor.resolveType
+     * @param {SourceFile} relativeTo - file to which the resolved type should be relative to
      * @public
      */
     resolveInlineDeclaration(items, into, relativeTo) {
@@ -56,10 +56,10 @@ class InlineDeclarationResolver {
 
     /**
      * Visits a single element in an entity.
-     * @param {string} name name of the element
-     * @param {import('./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 {string} name - name of the element
+     * @param {import('./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.
      * @public
      */
     visitElement(name, element, file, buffer = file.classes) {
@@ -71,7 +71,7 @@ class InlineDeclarationResolver {
         this.depth--
         if (this.depth === 0) {
             this.printInlineType(name, type, buffer)
-        }        
+        }
         return type
     }
 
@@ -88,8 +88,8 @@ class InlineDeclarationResolver {
     /**
      * It returns TypeScript datatype for provided TS property
      * @param {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection } }} type
-     * @param {string} typeName name of the TypeScript property
-     * @return {string} the datatype to be presented on TypeScript layer
+     * @param {string} typeName - name of the TypeScript property
+     * @returns {string} the datatype to be presented on TypeScript layer
      * @public
      */
     getPropertyDatatype(type, typeName = type.typeName) {
@@ -118,7 +118,7 @@ class InlineDeclarationResolver {
      * T['a']['b']  // number
      * ```
      * but especially with inline declarations, the access will differ between flattened and nested representations.
-     * @param {string[]} members a list of members, in the above example it would be `['a', 'b']`
+     * @param {string[]} members - a list of members, in the above example it would be `['a', 'b']`
      * @returns {string} type access string snippet. In the above sample, we would return `"['a']['b']"`
      * @public
      * @abstract

package/lib/components/reference.js

@@ -2,17 +2,16 @@
  * Check if an element references another type.
  * This happens for foreign key relationships
  * and for the typeof syntax.
- * 
+ *
  * ```cds
  * entity E {
- *   x: Integer
+ * x: Integer
  * }
- * 
+ *
  * entity F {
- *   y: E.x  // <- ref
+ * y: E.x  // <- ref
  * }
  * ```
- * 
  * @param {{type: any}} element
  * @returns boolean
  */

package/lib/components/resolver.js

@@ -10,34 +10,9 @@ const { isReferenceType } = require('./reference')
 const { isEntity } = require('../csn')
 const { baseDefinitions } = require('./basedefs')
 
-/** @typedef {{ cardinality?: { max?: '*' | number } }} EntityCSN */
-/** @typedef {{ definitions?: Object<string, EntityCSN> }} CSN */
 /** @typedef {import('../visitor').Visitor} Visitor */
-
-/**
- * When nested inline types require additional imports. E.g.:
- * ```cds
- * // mymodel.cds
- * Foo {
- *   bar: {
- *     baz: a.b.c.Baz // need to require a.b.c in mymodel.cds!
- *   }
- * }
- * ```
- * @typedef {{
- *    isBuiltin: boolean,
- *    isDeepRequire: boolean,
- *    isNotNull: boolean,
- *    isInlineDeclaration: boolean,
- *    isForeignKeyReference: boolean,
- *    isArray: boolean,
- *    type: string, 
- *    path?: Path,
- *    csn?: CSN,
- *    imports: Path[] 
- *    inner: TypeResolveInfo
- * }} TypeResolveInfo
-*/
+/** @typedef {import('../typedefs').resolver.CSN} CSN */
+/** @typedef {import('../typedefs').resolver.TypeResolveInfo} TypeResolveInfo */
 
 class BuiltinResolver {
     /**
@@ -82,7 +57,7 @@ class BuiltinResolver {
     }
 
     /**
-     * @param {string | string[]} type name or parts of the type name split on dots
+     * @param {string | string[]} t - name or parts of the type name split on dots
      * @returns {string | undefined | false} if t refers to a builtin, the name of the corresponding TS type is returned.
      *   If t _looks like_ a builtin (`cds.X`), undefined is returned.
      *   If t is obviously not a builtin, false is returned.
@@ -172,7 +147,7 @@ class Resolver {
     /**
      * TODO: this should probably be a class where we can also cache the properties
      * and only retrieve them on demand
-     * @typedef {Object} Untangled 
+     * @typedef {object} Untangled 
      * @property {string[]} scope in case the entity is wrapped in another entity `a.b.C.D.E.f.g` -> `[C,D]`
      * @property {string} name name of the leaf entity `a.b.C.D.E.f.g` -> `E`
      * @property {string[]} property the property access path `a.b.C.D.E.f.g` -> `[f,g]`
@@ -183,7 +158,7 @@ class Resolver {
      * Conveniently combines resolveNamespace and trimNamespace
      * 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.
+     * @param {string} fq - the fully qualified name of an entity.
      * @returns {Untangled} untangled qualifier
      */
     untangle(fq) {
@@ -212,7 +187,7 @@ class Resolver {
      * a.b.c.Foo -> Foo
      * Bar -> Bar
      * sap.cap.Book.text -> Book.text (assuming Book and text are both of kind "entity")
-     * @param {string} p path
+     * @param {string} p - path
      * @returns {string} the entity name without leading namespace.
      */
     trimNamespace(p) {
@@ -236,7 +211,7 @@ class Resolver {
      * 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.
-     * @param {string} p path
+     * @param {string} p - path
      * @example
      * ```
      * namespace namespace;
@@ -249,7 +224,6 @@ class Resolver {
      *   x: namespace.Entity.x.y.z;
      * }
      * ```
-     * 
      * @example 
      * ```js
      * findPropertyAccess('namespace') // []
@@ -292,8 +266,8 @@ class Resolver {
      * - type definitions, which are not inflected
      * - inline type definitions, which don't really have a linguistic plural,
      *   but need to expressed as array type to be consumable by the likes of Composition.of.many<T>
-     * @param {import('./resolver').TypeResolveInfo} typeInfo information about the type gathered so far.
-     * @param {string} [namespace] namespace the type occurs in. If passed, will be shaved off from the name
+     * @param {import('./resolver').TypeResolveInfo} typeInfo - information about the type gathered so far.
+     * @param {string} [namespace] - namespace the type occurs in. If passed, will be shaved off from the name
      * @returns {Inflection}
      */
     inflect(typeInfo, namespace) {
@@ -364,9 +338,8 @@ class Resolver {
      * 1. add an import of model1 to model2 with proper path resolution and alias, e.g. "import * as m1 from './model1'"
      * 2. resolve any singular/ plural issues and association/ composition around it
      * 3. return a properly prefixed name to use within model2.d.ts, e.g. "m1.Foo"
-     *
-     * @param {CSN} element the CSN element to resolve the type for.
-     * @param {SourceFile} file source file for context.
+     * @param {CSN} element - the CSN element to resolve the type for.
+     * @param {SourceFile} file - source file for context.
      * @returns {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection } }} info about the resolved type
      */
     resolveAndRequire(element, file) {
@@ -476,7 +449,7 @@ class Resolver {
 
     /**
      * Attempts to retrieve the max cardinality of a CSN for an entity.
-     * @param {EntityCSN} element csn of entity to retrieve cardinality for
+     * @param {EntityCSN} element - csn of entity to retrieve cardinality for
      * @returns {number} max cardinality of the element.
      * If no cardinality is attached to the element, cardinality is 1.
      * If it is set to '*', result is Infinity.
@@ -489,7 +462,7 @@ class Resolver {
     /**
      * Resolves the fully qualified name of an entity to its parent entity.
      * resolveParent(a.b.c.D) -> CSN {a.b.c}
-     * @param {string} name fully qualified name of the entity to resolve the parent of.
+     * @param {string} name - fully qualified name of the entity to resolve the parent of.
      * @returns {CSN} the resolved parent CSN.
      */
     resolveParent(name) {
@@ -502,7 +475,7 @@ class Resolver {
      * read from left to right which does not contain a kind 'context' or 'service'.
      * That is, if in the above example 'D' is a context and 'E' is a service,
      * the resulting namespace is 'a.b.c'.
-     * @param {string[] | string} pathParts the distinct parts of the namespace, i.e. ['a','b','c','D','E'] or a single path interspersed with periods
+     * @param {string[] | string} pathParts - the distinct parts of the namespace, i.e. ['a','b','c','D','E'] or a single path interspersed with periods
      * @returns {string} the namespace's name, i.e. 'a.b.c'.
      */
     resolveNamespace(pathParts) {
@@ -528,8 +501,8 @@ class Resolver {
     /**
      * Resolves an element's type to either a builtin or a user defined type.
      * Enriched with additional information for improved printout (see return type).
-     * @param {CSN} element the CSN element to resolve the type for.
-     * @param {SourceFile} file source file for context.
+     * @param {CSN} element - the CSN element to resolve the type for.
+     * @param {SourceFile} file - source file for context.
      * @returns {TypeResolveInfo} description of the resolved type
      */
     resolveType(element, file) {
@@ -611,15 +584,14 @@ class Resolver {
      * We can encounter declarations like:
      *
      * record : array of {
-     *   column : String;
-     *   data   : String;
+     * column : String;
+     * data   : String;
      * }
      *
      * These have to be resolved to a new type.
-     *
-     * @param {any[]} items the properties of the inline declaration.
-     * @param {TypeResolveInfo} into @see resolveType()
-     * @param {SourceFile} relativeTo the sourcefile in which we have found the reference to the type.
+     * @param {any[]} items - the properties of the inline declaration.
+     * @param {TypeResolveInfo} into - @see resolveType()
+     * @param {SourceFile} relativeTo - the sourcefile in which we have found the reference to the type.
      *  This is important to correctly detect when a field in the inline declaration is referencing
      *  types from the CWD. In that case, we will not add an import for that type and not add a namespace-prefix.
      */
@@ -630,8 +602,8 @@ class Resolver {
     /**
      * Attempts to resolve a type that could reference another type.
      * @param {?} val
-     * @param {TypeResolveInfo} into see resolveType()
-     * @param {SourceFile} file only needed as we may call #resolveInlineDeclarationType from here. Will be expelled at some point.
+     * @param {TypeResolveInfo} into - see resolveType()
+     * @param {SourceFile} file - only needed as we may call #resolveInlineDeclarationType from here. Will be expelled at some point.
      */
     resolvePotentialReferenceType(val, into, file) {
         // FIXME: get rid of file parameter! it is only used to pass to #resolveInlineDeclarationType
@@ -650,8 +622,8 @@ class Resolver {
      * Attempts to resolve a string to a type.
      * String is supposed to refer to either a builtin type
      * or any type defined in CSN.
-     * @param {string} t fully qualified type, like cds.String, or a.b.c.d.Foo
-     * @param {TypeResolveInfo} into optional dictionary to fill by reference, see resolveType()
+     * @param {string} t - fully qualified type, like cds.String, or a.b.c.d.Foo
+     * @param {TypeResolveInfo} into - optional dictionary to fill by reference, see resolveType()
      * @returns @see resolveType
      */
     #resolveTypeName(t, into) {

package/lib/components/wrappers.js

@@ -5,57 +5,57 @@ const base = '__'
 
 /**
  * Wraps type into association to scalar.
- * @param {string} t the singular type name. 
+ * @param {string} t - the singular type name. 
  * @returns {string}
  */
 const createToOneAssociation = t => `${base}.Association.to<${t}>`
 
 /**
  * Wraps type into association to vector.
- * @param {string} t the singular type name. 
+ * @param {string} t - the singular type name. 
  * @returns {string}
  */
 const createToManyAssociation = t => `${base}.Association.to.many<${t}>`
 
 /**
  * Wraps type into composition of scalar.
- * @param {string} t the singular type name. 
+ * @param {string} t - the singular type name. 
  * @returns {string}
  */
 const createCompositionOfOne = t => `${base}.Composition.of<${t}>`
 
 /**
  * Wraps type into composition of vector.
- * @param {string} t the singular type name. 
+ * @param {string} t - the singular type name. 
  * @returns {string}
  */
 const createCompositionOfMany = t => `${base}.Composition.of.many<${t}>`
 
 /**
  * Wraps type into an array.
- * @param {string} t the singular type name. 
+ * @param {string} t - the singular type name. 
  * @returns {string}
  */
 const createArrayOf = t => `Array<${t}>`
 
 /**
  * Wraps type into object braces
- * @param {string} t the properties, stringified and comma separated.
+ * @param {string} t - the properties, stringified and comma separated.
  * @returns {string}
  */
 const createObjectOf = t => `{${t}}`
 
 /**
  * Wraps type into a deep require (removes all posibilities of undefined recursively).
- * @param {string} t the singular type name. 
- * @param {string?} lookup a property lookup of the required type (`['Foo']`)
+ * @param {string} t - the singular type name. 
+ * @param {string?} lookup - a property lookup of the required type (`['Foo']`)
  * @returns {string}
  */
 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} 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(...)`.
  */

package/lib/csn.js

@@ -5,6 +5,7 @@ const annotation = '@odata.draft.enabled'
  * 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.
+ * @param {any} entity
  */
 const isView = entity => entity.query && !entity.projection
 
@@ -21,6 +22,7 @@ const isType = entity => entity?.kind === 'type'
 const isEntity = entity => entity?.kind === 'entity'
 
 /**
+ * @param {any} entity
  * @see isView
  * Unresolved entities have to be looked up from inferred csn.
  */
@@ -51,8 +53,8 @@ class DraftUnroller {
     get csn() { return this.#csn }
 
     /**
-     * @param entity {object | string} - entity to set draftable annotation for.
-     * @param value {boolean} - whether the entity is draftable.
+     * @param {object | string} entity - entity to set draftable annotation for.
+     * @param {boolean} value - whether the entity is draftable.
      */
     #setDraftable(entity, value) { 
         if (typeof entity === 'string') entity = this.#getDefinition(entity)
@@ -67,7 +69,7 @@ class DraftUnroller {
     }
 
     /**
-     * @param entity {object | string} - entity to look draftability up for.
+     * @param {object | string} entityOrName - entity to look draftability up for.
      * @returns {boolean}
      */
     #getDraftable(entityOrName) {
@@ -80,7 +82,7 @@ class DraftUnroller {
     }
 
     /**
-     * @param name {string} - name of the entity.
+     * @param {string} name - name of the entity.
      */
     #getDefinition(name) { return this.csn.definitions[name] }
 
@@ -88,8 +90,7 @@ class DraftUnroller {
      * Propagate draft annotations through inheritance (includes).
      * The latest annotation through the inheritance chain "wins".
      * Annotations on the entity itself are always queued last, so they will always be decisive over ancestors.
-     * 
-     * @param entity {object} - entity to pull draftability from its parents.
+     * @param {object} entity - entity to pull draftability from its parents.
      */
     #propagateInheritance(entity) {
         const annotations = (entity?.includes ?? []).map(parent => this.#getDraftable(parent))
@@ -118,8 +119,7 @@ class DraftUnroller {
     /**
      * If an entity E is draftable and contains any composition of entities,
      * then those entities also become draftable. Recursively.
-     * 
-     * @param entity {object} - entity to propagate all compositions from.
+     * @param {object} entity - entity to propagate all compositions from.
      */
     #propagateCompositions(entity) {
         if (!this.#getDraftable(entity)) return
@@ -160,6 +160,7 @@ class DraftUnroller {
  * (a) aspects via `A: B`, where `B` is draft enabled.
  * Note that when an entity extends two other entities of which one has drafts enabled and
  * one has not, then the one that is later in the list of mixins "wins":
+ * @param {any} csn
  * @example
  * ```ts
  * ＠odata.draft.enabled true
@@ -194,13 +195,13 @@ function unrollDraftability(csn) {
 
 /**
  * Propagates keys elements through the CSN. This includes
- * 
+ *
  * (a) keys that are explicitly declared as key in an entity
  * (b) keys from aspects the entity extends
- * 
+ *
  * This explicit propagation is required to add foreign key relations
  * to referring entities.
- * 
+ * @param {any} csn
  * @example
  * ```cds
  * entity A: cuid { key name: String; }
@@ -218,7 +219,6 @@ function unrollDraftability(csn) {
  *   ref_name: String;
  * }
  * ```
- * @returns {{[key: string]: object}}
  */
 function propagateForeignKeys(csn) {
     for (const element of Object.values(csn.definitions)) {
@@ -249,6 +249,10 @@ function propagateForeignKeys(csn) {
     }
 }
 
+/**
+ *
+ * @param {any} csn
+ */
 function amendCSN(csn) {
     unrollDraftability(csn)
     propagateForeignKeys(csn)

package/lib/file.js

@@ -10,7 +10,7 @@ const { createObjectOf } = require('./components/wrappers')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
-/** @typedef {Object<string, Buffer>} Namespace */ 
+/** @typedef {import('./typedefs').file.Namespace} Namespace */ 
 
 class File {
     /**
@@ -79,7 +79,7 @@ class Library extends File {
 
     /**
      * Whether this library offers an entity of a given type (fully qualified).
-     * @param {string} entity the entity's name, e.g. cap.hana.TINYINT
+     * @param {string} entity - the entity's name, e.g. cap.hana.TINYINT
      * @returns {boolean} true, iff the namespace inferred from the passed string matches that of this library 
      *          and this library contains a class of that name. i.e.:
      *          ```js
@@ -102,7 +102,7 @@ class SourceFile extends File {
         super()
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
-        /** @type {Object} */
+        /** @type {object} */
         this.imports = {}
         /** @type {Buffer} */
         this.preamble = new Buffer()
@@ -122,9 +122,9 @@ class SourceFile extends File {
         this.aspects = new Buffer()
         /** @type {Namespace} */
         this.namespaces = {}
-        /** @type {Object<string, any>} */
+        /** @type {{[key: string]: any}} */
         this.classNames = {} // for .js file
-        /** @type {Object<string, any>} */
+        /** @type {{[key: string]: any}} */
         this.typeNames = {}
         /** @type {[string, string, string][]} */
         this.inflections = []
@@ -134,7 +134,7 @@ class SourceFile extends File {
 
     /**
      * Stringifies a lambda expression.
-     * @param {{name: string, parameters: [string, string][], returns: string, initialiser: string}} - name, parameters, return type, and initialiser expression
+     * @param {{name: string, parameters: [string, string][], returns: string, initialiser: string}} param - name, parameters, return type, and initialiser expression
      * @returns {string} - the stringified lambda
      * @example
      * ```js
@@ -150,7 +150,6 @@ class SourceFile extends File {
      * The reason for this is that the CDS runtime actually treats the function parameters as a named object. This can not be rectified via
      * type magic, as parameter names do not exist on type level. So we can not use these names to reuse them as object properties.
      * Instead, we generate this utility object for the runtime to use:
-     * 
      * @example
      * ```js
      * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
@@ -176,9 +175,9 @@ class SourceFile extends File {
      * Adds a pair of singular and plural inflection.
      * These are later used to generate the singular -> plural
      * aliases in the index.js file.
-     * @param {string} singular singular type without namespace.
-     * @param {string} plural plural type without namespace
-     * @param {string} original original entity name without namespace. 
+     * @param {string} singular - singular type without namespace.
+     * @param {string} plural - plural type without namespace
+     * @param {string} original - original entity name without namespace. 
      *        In many cases this will be the same as plural.
      */
     addInflection(singular, plural, original) {
@@ -187,10 +186,10 @@ class SourceFile extends File {
 
     /**
      * Adds a function definition in form of a arrow function to the file.
-     * @param {string} name name of the function
-     * @param {{relative: string | undefined, local: boolean, posix: boolean}} parameters list of parameters, passed as [name, type] pairs
+     * @param {string} name - name of the function
+     * @param {{relative: string | undefined, local: boolean, posix: boolean}} parameters - list of parameters, passed as [name, type] pairs
+     * @param {string} returns - the return type of the function
      * @param {'function' | 'action'} kind
-     * @param returns the return type of the function
      */
     addOperation(name, parameters, returns, kind) {
         //this.operations.buffer.add("// operation")
@@ -201,7 +200,7 @@ class SourceFile extends File {
     /**
      * Retrieves or creates and retrieves a sub namespace
      * with a given name.
-     * @param {string} name of the sub namespace.
+     * @param {string} name - of the sub namespace.
      * @returns {Namespace} the sub namespace.
      */
     getSubNamespace(name) {
@@ -221,28 +220,26 @@ class SourceFile extends File {
 
     /**
      * Adds an enum to this file.
-     * @param {string} fq fully qualified name of the enum (entity name within CSN)
-     * @param {string} name local name of the enum
-     * @param {[string, string][]} kvs list of key-value pairs
-     * @param {string} [property] property to which the enum is attached.
+     * @param {string} fq - fully qualified name of the enum (entity name within CSN)
+     * @param {string} name - local name of the enum
+     * @param {[string, string][]} kvs - list of key-value pairs
+     * @param {string?} property - property to which the enum is attached.
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
      */
-    addEnum(fq, name, kvs) {
+    addEnum(fq, name, kvs, property) {
         this.enums.data.push({ name, fq, kvs })
         printEnum(this.enums.buffer, name, kvs)
     }
 
     /**
      * Adds an inline enum to this file.
-     * @param {string} entityCleanName name of the entity the enum is attached to without namespace
-     * @param {string} entityFqName name of the entity the enum is attached to with namespace
-     * 
-     * @param {string} propertyName property to which the enum is attached. 
-     * @param {[string, string][]} kvs list of key-value pairs
+     * @param {string} entityCleanName - name of the entity the enum is attached to without namespace
+     * @param {string} entityFqName - name of the entity the enum is attached to with namespace
+     * @param {string} propertyName - property to which the enum is attached. 
+     * @param {[string, string][]} kvs - list of key-value pairs
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
-     * 
      * @example
      * ```js
      * addInlineEnum('Books.genre', 'Books', 'genre', [['horror','horror']])
@@ -279,8 +276,8 @@ class SourceFile extends File {
      * This differs from writing to the classes buffer,
      * as it is just a cache to collect all classes that 
      * are supposed to be present in this file. 
-     * @param {string} clean cleaned name of the class 
-     * @param {string} fq fully qualified name, including the namespace
+     * @param {string} clean - cleaned name of the class 
+     * @param {string} fq - fully qualified name, including the namespace
      */
     addClass(clean, fq) {
         this.classNames[clean] = fq
@@ -289,8 +286,8 @@ class SourceFile extends File {
     /**
      * Adds an event to this file.
      * are supposed to be present in this file. 
-     * @param {string} name cleaned name of the event
-     * @param {string} fq fully qualified name, including the namespace
+     * @param {string} name - cleaned name of the event
+     * @param {string} fq - fully qualified name, including the namespace
      */
     addEvent(name, fq) {
         this.events.fqs.push({ name, fq })
@@ -298,7 +295,7 @@ class SourceFile extends File {
 
     /**
      * Adds an import if it does not exist yet.
-     * @param {Path} imp qualifier for the namespace to import.
+     * @param {Path} imp - qualifier for the namespace to import.
      */
     addImport(imp) {
         const dir = imp.asDirectory({relative: this.path.asDirectory()})
@@ -310,7 +307,7 @@ class SourceFile extends File {
     /**
      * Adds an arbitrary piece of code that is added
      * right after the imports.
-     * @param {string} code the preamble code.
+     * @param {string} code - the preamble code.
      */
     addPreamble(code) {
         this.preamble.add(code)
@@ -318,9 +315,9 @@ class SourceFile extends File {
 
     /**
      * Adds a type alias to this file.
-     * @param {string} fq fully qualified name of the enum
-     * @param {string} name local name of the enum
-     * @param {string} rhs the right hand side of the assignment
+     * @param {string} fq - fully qualified name of the enum
+     * @param {string} clean - local name of the enum
+     * @param {string} rhs - the right hand side of the assignment
      */
     addType(fq, clean, rhs) {
         this.typeNames[clean] = fq
@@ -331,7 +328,7 @@ class SourceFile extends File {
      * Adds a service to the file.
      * We consider each service its own distinct namespace and therefore expect
      * at most one service per file.
-     * @param {string} fq the fully qualified name of the service
+     * @param {string} fq - the fully qualified name of the service
      */
     addService(fq) {
         // FIXME: warn the user when they're trying to add an entity/ type/ enum called "name", which will override our name export
@@ -458,7 +455,7 @@ class Buffer {
 
     /**
      * Concats all elements in the buffer into a single string.
-     * @param {string} glue string to intersperse all buffer contents with
+     * @param {string} glue - string to intersperse all buffer contents with
      * @returns {string} string spilled buffer contents.
      */
     join(glue = '\n') {
@@ -482,7 +479,7 @@ class Buffer {
 
     /**
      * Adds an element to the buffer with one level of indent.
-     * @param {string | (() => void)} part either a string or a function. If it is a string, it is added to the buffer. 
+     * @param {string | (() => void)} part - either a string or a function. If it is a string, it is added to the buffer. 
      * If not, it is expected to be a function that manipulates the buffer as a side effect.
      */
     addIndented(part) {
@@ -497,9 +494,9 @@ class Buffer {
 
     /**
      * Adds an element to a buffer with one level of indent and and opener and closer surrounding it.
-     * @param {string} opener the string to put before the indent
-     * @param {string} content the content to indent (see {@link addIndented})
-     * @param {string} closer the string to put after the indent
+     * @param {string} opener - the string to put before the indent
+     * @param {string} content - the content to indent (see {@link addIndented})
+     * @param {string} closer - the string to put after the indent
      */
     addIndentedBlock(opener, content, closer) {
         this.add(opener)
@@ -514,8 +511,8 @@ class Buffer {
 class Path {
 
     /**
-     * @param {string[]} parts parts of the path. 'a.b.c' -> ['a', 'b', 'c']
-     * @param kind FIXME: currently unused
+     * @param {string[]} parts - parts of the path. 'a.b.c' -> ['a', 'b', 'c']
+     * @param {string} kind - FIXME: currently unused
      */
     constructor(parts, kind) {
         this.parts = parts
@@ -531,9 +528,10 @@ class Path {
 
     /**
      * Transfoms the Path into a directory path.
-     * @param {string?} params.relative if defined, the path is constructed relative to this directory
-     * @param {boolean} params.local if set to true, './' is prefixed to the directory
-     * @param {boolean} params.posix if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
+     * @param {object} params
+     * @param {string?} params.relative - if defined, the path is constructed relative to this directory
+     * @param {boolean} params.local - if set to true, './' is prefixed to the directory
+     * @param {boolean} params.posix - if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
      * @returns {string} directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
      */
     asDirectory(params = {}) {
@@ -567,6 +565,7 @@ class Path {
     }
 
     /**
+     * @param {string} relative
      * @returns {boolean} true, iff the Path refers to the current working directory, aka './'
      */
     isCwd(relative = undefined) {
@@ -590,7 +589,7 @@ class FileRepository {
     /**
      * Determines the file corresponding to the namespace.
      * If no such file exists yet, it is created first.
-     * @param {string | Path} path the name of the namespace (foo.bar.baz)
+     * @param {string | Path} path - the name of the namespace (foo.bar.baz)
      * @returns {SourceFile} the file corresponding to that namespace name
      */
     getNamespaceFile(path) {
@@ -610,8 +609,8 @@ class FileRepository {
  * Writes the files to disk. For each source, a index.d.ts holding the type definitions
  * and a index.js holding implementation stubs is generated at the appropriate directory.
  * Missing directories are created automatically and asynchronously.
- * @param {string} root root directory to prefix all directories with
- * @param {File[]} sources source files to write to disk
+ * @param {string} root - root directory to prefix all directories with
+ * @param {File[]} sources - source files to write to disk
  * @returns {Promise<string[]>} Promise that resolves to a list of all directory paths pointing to generated files.
  */
 const writeout = async (root, sources) =>

package/lib/logging.js

@@ -25,7 +25,7 @@ class Logger {
 
     /**
      * Add all log levels starting at level.
-     * @param {number} baseLevel level to start from.
+     * @param {number} baseLevel - level to start from.
      */
     addFrom(baseLevel) {
         const vals = Object.values(Levels)
@@ -37,7 +37,7 @@ class Logger {
 
     /**
      * Adds a log level to react to.
-     * @param {number} level the level to react to. 
+     * @param {number} level - the level to react to. 
      */
     add(level) {
         this.mask = this.mask | level
@@ -45,7 +45,7 @@ class Logger {
 
     /**
      *  Ignores a log level.
-     * @param {number} level the level to ignore.
+     * @param {number} level - the level to ignore.
      */
     ignore(level) {
         this.mask = this.mask ^ level
@@ -56,8 +56,8 @@ class Logger {
      * Only iff levelName is a valid log level
      * and the corresponding number if part of mask,
      * the message gets logged.
-     * @param {Levels} levelName name of the log level.
-     * @param {string} message message to log.
+     * @param {Levels} levelName - name of the log level.
+     * @param {string} message - message to log.
      */
     _log(levelName, message) {
         const level = Levels[levelName]

package/lib/typedefs.d.ts

@@ -0,0 +1,75 @@
+export module resolver {
+    export type EntityCSN = {
+        cardinality?: { max?: '*' | number }
+    }
+
+    export type CSN = {
+        definitions?: { [key: string]: EntityCSN }
+    }
+
+    /**
+     * When nested inline types require additional imports. E.g.:
+     * ```cds
+     * // mymodel.cds
+     * Foo {
+     *   bar: {
+     *     baz: a.b.c.Baz // need to require a.b.c in mymodel.cds!
+     *   }
+     * }
+     * ```
+     */
+    export type TypeResolveInfo = {
+        isBuiltin: boolean,
+        isDeepRequire: boolean,
+        isNotNull: boolean,
+        isInlineDeclaration: boolean,
+        isForeignKeyReference: boolean,
+        isArray: boolean,
+        type: string,
+        path?: Path,
+        csn?: CSN,
+        imports: Path[]
+        inner: TypeResolveInfo
+    }
+}
+
+export module util {
+    export type Annotations = {
+        name?: string,
+        '@singular'?: string,
+        '@plural'?: string
+    }
+
+    export type CommandLineFlags = {
+        desc: string,
+        default?: any
+    }
+
+    export type ParsedFlag = {
+        positional: string[],
+        named: { [key: string]: any }
+    }
+}
+
+export module visitor {
+    export type CompileParameters = {
+        outputDirectory: string,
+        logLevel: number,
+        jsConfigPath?: string,
+    }
+
+    export type VisitorOptions = {
+        propertiesOptional: boolean,
+        inlineDeclarations: 'flat' | 'structured',
+    }
+
+    export type Inflection = {
+        typeName: string,
+        singular: string,
+        plural: string
+    }
+}
+
+export module file {
+    export type Namespace = Object<string, Buffer>
+}

package/lib/util.js

@@ -1,8 +1,6 @@
-/**
- * @typedef { {name?: string, '@singular'?: string, '@plural'?: string,} } Annotations
- * @typedef { {desc: string, default?: any} } CommandlineFlag
- * @typedef { {positional: string[], named: Object<string, any>} } ParsedFlags
-*/
+/** @typedef { import('./typedefs').util.Annotations} Annotations */
+/** @typedef { import('./typedefs').util.CommandLineFlags } CommandlineFlag */
+/** @typedef { import('./typedefs').util.ParsedFlag } ParsedFlags */
 
 // inflection functions are stolen from github/cap/dev/blob/main/etc/inflect.js
 
@@ -25,7 +23,7 @@ const annotations = {
  * from a CSN. Valid annotations are listed in util.annotations
  * and their precedence is in order of definition.
  * If no singular is specified at all, undefined is returned.
- * @param {Object} csn the CSN of an entity to check
+ * @param {object} csn - the CSN of an entity to check
  * @returns {string | undefined} the singular annotation or undefined
  */
 const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.hasOwn(csn, a))]
@@ -35,22 +33,22 @@ const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.h
  * from a CSN. Valid annotations are listed in util.annotations
  * and their precedence is in order of definition.
  * If no plural is specified at all, undefined is returned.
- * @param {Object} csn the CSN of an entity to check
+ * @param {object} csn - the CSN of an entity to check
  * @returns {string | undefined} the plural annotation or undefined
  */
 const getPluralAnnotation = csn => csn[annotations.plural.find(a => Object.hasOwn(csn, a))]
 
 /**
-  * Users can specify that they want to refer to localisation
-  * using the syntax {i18n>Foo}, where Foo is the name of the
-  * entity as found in the .cds file
-  * (see: https://pages.github.tools.sap/cap/docs/guides/i18n)
-  * As this throws off the naming, we remove this wrapper
-  * 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
-  */
+ * Users can specify that they want to refer to localisation
+ * using the syntax {i18n>Foo}, where Foo is the name of the
+ * entity as found in the .cds file
+ * (see: https://pages.github.tools.sap/cap/docs/guides/i18n)
+ * As this throws off the naming, we remove this wrapper
+ * 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>(.*)\}/)
     return match ? match[1] : name
@@ -59,8 +57,8 @@ const unlocalize = name => {
 /**
  * Attempts to derive the singular form of an English noun.
  * If '@singular' is passed as annotation, that is preferred.
- * @param {Annotations} dn annotations
- * @param {boolean?} stripped if true, leading namespace will be stripped
+ * @param {Annotations} dn - annotations
+ * @param {boolean?} stripped - if true, leading namespace will be stripped
  */
 const singular4 = (dn, stripped = false) => {
     let n = dn.name || dn
@@ -91,8 +89,8 @@ const singular4 = (dn, stripped = false) => {
 /**
  * Attempts to derive the plural form of an English noun.
  * If '@plural' is passed as annotation, that is preferred. 
- * @param {Annotations} dn annotations
- * @param {boolean} stripped if true, leading namespace will be stripped
+ * @param {Annotations} dn - annotations
+ * @param {boolean} stripped - if true, leading namespace will be stripped
  */
 const plural4 = (dn, stripped) => {
     let n = dn.name || dn
@@ -114,8 +112,8 @@ const plural4 = (dn, stripped) => {
 /**
  * Performs a deep merge of the passed objects into the first object. 
  * See Object.assign(target, source).
- * @param {Object} target object to assign into.
- * @param {Object} source object to assign from.
+ * @param {object} target - object to assign into.
+ * @param {object} source - object to assign from.
  */
 const deepMerge = (target, source) => {
     Object.keys(target)
@@ -134,8 +132,8 @@ const deepMerge = (target, source) => {
  * will cause an error.
  * Named parameters that are either not specified or do not have a value assigned to them may draw a default value 
  * from their definition in validFlags.
- * @param {string[]} argv list of command line arguments
- * @param {Object<string, CommandlineFlag>} validFlags allowed flags. May specify default values.
+ * @param {string[]} argv - list of command line arguments
+ * @param {{[key: string]: CommandlineFlag}} validFlags - allowed flags. May specify default values.
  * @returns {ParsedFlags}
  */
 const parseCommandlineArgs = (argv, validFlags) => {

package/lib/visitor.js

@@ -15,33 +15,10 @@ const { empty } = require('./components/typescript')
 const { baseDefinitions } = require('./components/basedefs')
 
 /** @typedef {import('./file').File} File */
-/** @typedef {{ entity: String }} Context */
-
-/** 
- * @typedef { {
- *    outputDirectory: string, 
- *    logLevel: number, 
- *    jsConfigPath?: string
- * }} CompileParameters
- */
-
-/** 
- * - `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable)
- * - `inlineDeclarations = 'structured'` -> @see inline.StructuredInlineDeclarationResolver
- * - `inlineDeclarations = 'flat'` -> @see inline.FlatInlineDeclarationResolver
- * @typedef { { 
-  *    propertiesOptional: boolean,
-  *    inlineDeclarations: 'flat' | 'structured',
- * }} VisitorOptions 
- */
-
-/**
-  * @typedef {{
-  *   typeName: string,
-  *   singular: string,
-  *   plural: string
-  * }} Inflection
-  */
+/** @typedef {import('./typedefs').visitor.Context} Context */
+/** @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters */
+/** @typedef {import('./typedefs').visitor.VisitorOptions} VisitorOptions */
+/** @typedef {import('./typedefs').visitor.Inflection} Inflection */
 
 const defaults = {
     // FIXME: add defaults for remaining parameters
@@ -61,8 +38,9 @@ class Visitor {
     }
 
     /**
-     * @param {{xtended: CSN, inferred: CSN}} csn root CSN
+     * @param {{xtended: CSN, inferred: CSN}} csn - root CSN
      * @param {VisitorOptions} options
+     * @param {Logger} logger
      */
     constructor(csn, options = {}, logger = new Logger()) {
         amendCSN(csn.xtended)
@@ -127,6 +105,7 @@ class Visitor {
     /**
      * Retrieves all the keys from an entity.
      * That is: all keys that are present in both inferred, as well as xtended flavour.
+     * @param {string} name
      * @returns {[string, object][]} array of key name and key element pairs
      */
     #keys(name) {
@@ -148,9 +127,9 @@ class Visitor {
      * - the function A(B) to mix the aspect into another class B
      * - 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} 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} name - the name of the entity
+     * @param {CSN} 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
      */
     #aspectify(name, entity, buffer, options = {}) {
@@ -178,13 +157,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 this.#keys(element.target)) {
-                            if (this.resolver.getMaxCardinality(element) === 1) {  // FIXME: kelement?
+                        for (const [kname, originalKeyElement] of this.#keys(element.target)) {
+                            if (this.resolver.getMaxCardinality(element) === 1 && typeof element.on !== 'object') {  // FIXME: kelement?
                                 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
+                                    const kelement = Object.assign(Object.create(originalKeyElement), { 
+                                        isRefNotNull: !!element.notNull || !!element.key 
+                                    })
                                     this.visitElement(foreignKey, kelement, file, buffer)
                                 }
                             }
@@ -439,8 +420,8 @@ 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} name 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 {string} name - 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.
      */
     visitEntity(name, entity) {
         switch (entity.kind) {
@@ -478,7 +459,7 @@ class Visitor {
      * refer to types via their alias that hides the aspectification.
      * If we attempt to directly refer to this alias while it has not been fully created,
      * that will result in a TS error.
-     * @param {String} entityName
+     * @param {string} entityName
      * @returns {boolean} true, if `entityName` refers to the surrounding class
      * @example
      * ```ts
@@ -494,10 +475,10 @@ class Visitor {
 
     /**
      * Visits a single element in an entity.
-     * @param {string} name name of the element
-     * @param {import('./components/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 {string} name - name of the element
+     * @param {import('./components/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.
      * @returns @see InlineDeclarationResolver.visitElement
      */
     visitElement(name, element, file, buffer) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.21.1",
+  "version": "0.22.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",
@@ -45,6 +45,7 @@
     "@stylistic/eslint-plugin-js": "^1.6.3",
     "acorn": "^8.10.0",
     "eslint": "^9",
+    "eslint-plugin-jsdoc": "^48.2.7",
     "globals": "^15.0.0",
     "jest": "^29",
     "typescript": ">=4.6.4"