@cap-js/cds-typer 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,10 +4,20 @@ 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.27.0 - TBD
+## Version 0.28.0 - TBD
+
+## Version 0.27.0 - 2024-10-02
+### Changed
+- Any configuration variable (via CLI or `cds.env`) can now be passed in snake_case in addition to camelCase
+- Action parameters are now generated as optional by default, which is how the runtime treats them. Mandatory parameters have to be marked as `not null` in CDS/CDL, or `notNull` in CSN.
+
+### Fixed
+- Fix build task for projects with spaces
+- Fixa bug where cds-typer would produce redundant type declarations when the model contains an associations to another entity's property
 
 ## Version 0.26.0 - 2024-09-11
 ### Added
+- Added a static `.keys` property in all entities. That property is dictionary which holds all properties as keys that are marked as `key` in CDS
 - Added a CLI option `--useEntitiesProxy`. When set to `true`, all entities are wrapped into `Proxy` objects during runtime, allowing top level imports of entity types.
 - Added a static `.kind` property for entities and types, which contains `'entity'` or `'type'` respectively
 - Apps need to provide `@sap/cds` version `8.2` or higher.
@@ -47,6 +57,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 
 ## Version 0.22.0 - 2024-06-20
+
 ### Fixed
 - Fixed a bug where keys would sometimes inconsistently become nullable
 

package/cds-plugin.js

@@ -36,7 +36,7 @@ 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.
- * @returns {Promise<void>}
+ * @returns {Promise<unknown>}
  */
 const rmFiles = async (dir, exts) => fs.existsSync(dir)
     ? Promise.all(
@@ -68,10 +68,15 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
 
     get #appFolder () { return cds?.env?.folders?.app ?? 'app' }
 
+    /**
+     * cds.env > tsconfig.compilerOptions.paths > '@cds-models' (default)
+     */
     get #modelDirectoryName () {
+        const outputDirectory = cds.env.typer?.outputDirectory
+        if (outputDirectory) return outputDirectory
         try {
             // expected format: { '#cds-models/*': [ './@cds-models/*/index.ts' ] }
-            //                                       ^^^^^^^^^^^^^^^
+            //                                          ^^^^^^^^^^^
             //                             relevant part - may be changed by user
             const config = JSON.parse(fs.readFileSync ('tsconfig.json', 'utf8'))
             const alias = config.compilerOptions.paths['#cds-models/*'][0]
@@ -89,7 +94,9 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
 
     async #runCdsTyper () {
         DEBUG?.('running cds-typer')
-        await typer.compileFromFile('*', { outputDirectory: this.#modelDirectoryName })
+        cds.env.typer ??= {}
+        cds.env.typer.outputDirectory ??= this.#modelDirectoryName
+        await typer.compileFromFile('*')
     }
 
     async #buildWithConfig () {
@@ -103,7 +110,7 @@ cds.build?.register?.('typescript', class extends cds.build.Plugin {
         DEBUG?.('building without config')
         // this will include gen/ that was created by the nodejs task
         // _within_ the project directory. So we need to remove it afterwards.
-        await exec(`npx tsc --outDir ${this.task.dest}`)
+        await exec(`npx tsc --outDir "${this.task.dest}"`)
         rmDirIfExists(path.join(this.task.dest, cds.env.build.target))
         rmDirIfExists(path.join(this.task.dest, this.#appFolder))
     }

package/lib/cli.js

@@ -2,20 +2,147 @@
 /* eslint-disable no-console */
 'use strict'
 
+/**
+ * @typedef {import('./typedefs').config.cli.ParameterSchema[number]} Parameter
+ */
+
 const cds = require('@sap/cds')
 const { compileFromFile } = require('./compile')
-const { parseCommandlineArgs } = require('./util')
+const { camelToSnake } = require('./util')
 const { deprecated, _keyFor } = require('./logging')
 const path = require('path')
 const { EOL } = require('node:os')
+const { camelSnakeHybrid, configuration } = require('./config')
 
 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 parameterTypes = {
+    boolean:
+    /**
+     * @param {Parameter} props - additional parameter properties
+     * @returns {Parameter}
+     */
+    props => ({...{
+        allowed: ['true', 'false'],
+        type: 'boolean',
+        postprocess: (/** @type {string} */ value) => value === 'true'
+    },
+    ...props})
+}
+
+/**
+ * Adds additional properties to the CLI parameter schema.
+ * @param {import('./typedefs').config.cli.ParameterSchema } flags - The CLI parameter schema.
+ * @returns {import('./typedefs').config.cli.ParameterSchema} - The enriched schema.
+ */
+const enrichFlagSchema = flags => {
+    const flagKeys = Object.keys(flags)
+    for (const [key, value] of Object.entries(flags)) {
+        /** @type {Parameter} */(value).camel = key;
+        /** @type {Parameter} */(value).snake = camelToSnake(key)
+    }
+    // non-enumerable utilities
+    Object.defineProperties(flags, {
+        hasFlag: {
+            value: (/** @type {string} **/ flag) => Object.values(flags).some(f => f.snake === flag || f.camel === flag)
+        },
+        keys: {
+            value: flagKeys
+        }
+    })
+    return camelSnakeHybrid(flags)
+}
+
+/**
+ * Parses command line arguments into named and positional parameters.
+ * Named parameters are expected to start with a double dash (--).
+ * If the next argument `B` after a named parameter `A` is not a named parameter itself,
+ * `B` is used as value for `A`.
+ * If `A` and `B` are both named parameters, `A` is just treated as a flag (and may receive a default value).
+ * Only named parameters that occur in validFlags are allowed. Specifying named flags that are not listed there
+ * 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 {import('./typedefs').config.cli.ParameterSchema} schema - allowed flags. May specify default values.
+ * @returns {import('./typedefs').config.cli.ParsedParameters} - parsed arguments
+ */
+const parseCommandlineArgs = (argv, schema) => {
+    const isFlag = (/** @type {string} */ arg) => arg.startsWith('--')
+    const positional = []
+    /** @type {import('./typedefs').config.cli.ParsedParameters['named']} */
+    const named = {}
+
+    let i = 0
+    while (i < argv.length) {
+        const originalArgName = argv[i]  // so our feedback to the user is less confusing
+        let arg = originalArgName
+        if (isFlag(arg)) {
+            arg = camelToSnake(arg.slice(2))
+            // @ts-expect-error - cba to add hasFlag to the general dictionary
+            if (!schema.hasFlag(arg)) {
+                throw new Error(`invalid named flag '${originalArgName}'`)
+            }
+            const next = argv[i + 1]
+            if (next && !isFlag(next)) {
+                named[arg] = { value: next, isDefault: false }
+                i++
+            } else {
+                named[arg] = { value: schema[arg].default, isDefault: true }
+            }
+
+            const { allowed, allowedHint } = schema[arg]
+            if (allowed && !allowed.includes(named[arg].value)) {
+                throw new Error(`invalid value '${named[arg]?.value ?? named[arg]}' for flag ${originalArgName}. Must be one of ${(allowedHint ?? allowed.join(', '))}`)
+            }
+        } else {
+            positional.push(arg)
+        }
+        i++
+    }
+
+    // enrich with defaults
+    /** @type {import('./typedefs').config.cli.ParameterSchema} */
+    const defaults = Object.entries(schema)
+        .filter(e => !!e[1].default)
+        .reduce((dict, [k, v]) => {
+            // @ts-expect-error - can't infer type of initial {}
+            dict[camelToSnake(k)] = { value: v.default, isDefault: true }
+            return dict
+        }, {})
+
+    const namedWithDefaults = {...defaults, ...named}
+
+    // apply postprocessing
+    for (const [key, {value}] of Object.entries(namedWithDefaults)) {
+        const { postprocess } = schema[key]
+        if (typeof postprocess === 'function') {
+            namedWithDefaults[key].value = postprocess(value)
+        }
+    }
+
+    return {
+        named: namedWithDefaults,
+        positional,
+    }
+}
+
+/**
+ * Adds CLI parameters to the configuration object.
+ * Precedence: CLI > env > default.
+ * @param {ReturnType<parseCommandlineArgs>['named']} params - CLI parameters.
+ */
+const addCLIParamsToConfig = params => {
+    for (const [key, value] of Object.entries(params)) {
+        if (!value.isDefault || Object.hasOwn(configuration, key)) {
+            configuration[key] = value.value
+        }
+    }
+}
 
-const flags = {
+const flags = enrichFlagSchema({
     outputDirectory: {
         desc: 'Root directory to write the generated files to.',
         default: './',
@@ -30,16 +157,24 @@ const flags = {
         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),
+        postprocess: level => {
+            const newLogLevel = deprecated[level]
+            if (newLogLevel) {
+                console.warn(`deprecated log level '${level}', use '${newLogLevel}' instead (changing this automatically for now).`)
+                return newLogLevel
+            }
+            return level
+        }
     },
     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.`,
-        type: 'string'
+        type: 'string',
+        postprocess: file => file && !file.endsWith('jsconfig.json') ? path.join(file, 'jsconfig.json') : path
     },
-    useEntitiesProxy: {
+    useEntitiesProxy: parameterTypes.boolean({
         desc: `If set to true the 'cds.entities' exports in the generated 'index.js'${EOL}files will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.${EOL}${EOL}WARNING: entity properties can still only be accessed after${EOL}'cds.entities' has been loaded`,
-        allowed: ['true', 'false'],
         default: 'false'
-    },
+    }),
     version: {
         desc: 'Prints the version of this tool.'
     },
@@ -48,17 +183,15 @@ const flags = {
         allowed: ['flat', 'structured'],
         default: 'structured'
     },
-    propertiesOptional: {
+    propertiesOptional: parameterTypes.boolean({
         desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
-        allowed: ['true', 'false'],
         default: 'true'
-    },
-    IEEE754Compatible: {
+    }),
+    IEEE754Compatible: parameterTypes.boolean({
         desc: `If set to true, floating point properties are generated${EOL}as IEEE754 compatible '(number | string)' instead of 'number'.`,
-        allowed: ['true', 'false'],
         default: 'false'
-    }
-}
+    })
+})
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'
 /**
@@ -74,19 +207,22 @@ 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)
+            flags.keys
                 .sort(([a], [b]) => a.localeCompare(b))
-                .map(([key, value]) => {
+                .map(key => {
+                    const value = flags[key]
                     let s = indent(`--${key}`, '  ')
-                    // @ts-expect-error - not going to check presence of each property. Same for the following expect-errors.
+                    const snake = camelToSnake(key)
+                    if (key !== snake) s += EOL + indent(`--${snake}`, '  ')
+                    // 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
+                    // ts-expect-error
                     else if (value.allowed) s += `: <${value.allowed.join(' | ')}>`
                     else if ('type' in value && value.type) s += `: <${value.type}>`
-                    // @ts-expect-error
+                    // ts-expect-error
                     if (value.defaultHint || value.default) {
                         s += EOL
-                        // @ts-expect-error
+                        // ts-expect-error
                         s += indent(`(default: ${value.defaultHint ?? value.default})`, '    ')
                     }
                     s += `${EOL2}${indent(value.desc, '    ')}`
@@ -96,7 +232,9 @@ const help = () => `SYNOPSIS${EOL2}` +
 
 const version = () => require('../package.json').version
 
-const main = async (/** @type {any} */ args) => {
+const prepareParameters = (/** @type {any[]} */ argv) => {
+    const args = parseCommandlineArgs(argv, flags)
+
     if ('help' in args.named) {
         console.log(help())
         process.exit(0)
@@ -109,27 +247,21 @@ const main = async (/** @type {any} */ args) => {
         console.log(hint())
         process.exit(1)
     }
-    if (args.named.jsConfigPath && !args.named.jsConfigPath.endsWith('jsconfig.json')) {
-        args.named.jsConfigPath = path.join(args.named.jsConfigPath, 'jsconfig.json')
-    }
-    const newLogLevel = deprecated[args.named.logLevel]
-    if (newLogLevel) {
-        console.warn(`deprecated log level '${args.named.logLevel}', use '${newLogLevel}' instead (changing this automatically for now).`)
-        args.named.logLevel = newLogLevel
-    }
 
-    compileFromFile(args.positional, {
-        // temporary fix until rootDir is faded out
-        outputDirectory: [args.named.outputDirectory, args.named.rootDir].find(d => d !== './') ?? './',
-        logLevel: args.named.logLevel,
-        useEntitiesProxy: args.named.useEntitiesProxy === 'true',
-        jsConfigPath: args.named.jsConfigPath,
-        inlineDeclarations: args.named.inlineDeclarations,
-        propertiesOptional: args.named.propertiesOptional === 'true',
-        IEEE754Compatible: args.named.IEEE754Compatible === 'true'
-    })
+    addCLIParamsToConfig(args.named)
+    return args
+}
+
+const main = async (/** @type {any[]} */ argv) => {
+    const { positional } = prepareParameters(argv)
+    compileFromFile(positional)
 }
 
 if (require.main === module) {
-    main(parseCommandlineArgs(process.argv.slice(2), flags))
+    main(process.argv.slice(2))
+}
+
+module.exports = {
+    flags,
+    prepareParameters
 }

package/lib/compile.js

@@ -7,10 +7,7 @@ const util = require('./util')
 const { writeout } = require('./file')
 const { Visitor } = require('./visitor')
 const { LOG, setLevel } = require('./logging')
-
-/**
- * @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters
- */
+const { configuration } = require('./config')
 
 /**
  * Writes the accompanying jsconfig.json file to the specified paths.
@@ -40,31 +37,28 @@ const writeJsConfig = path => {
 /**
  * Compiles a CSN object to Typescript types.
  * @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) => {
-    const envSettings = cds.env?.typer ?? {}
-    parameters = { ...envSettings, ...parameters }
-    setLevel(parameters.logLevel)
-    if (parameters.jsConfigPath) {
-        writeJsConfig(parameters.jsConfigPath)
+const compileFromCSN = async csn => {
+
+    setLevel(configuration.logLevel)
+    if (configuration.jsConfigPath) {
+        writeJsConfig(configuration.jsConfigPath)
     }
     return writeout(
-        parameters.outputDirectory,
-        Object.values(new Visitor(csn, parameters).getWriteoutFiles())
+        configuration.outputDirectory,
+        Object.values(new Visitor(csn).getWriteoutFiles())
     )
 }
 
 /**
  * Compiles a .cds file to Typescript types.
  * @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) => {
+const compileFromFile = async inputFile => {
     const paths = typeof inputFile === 'string' ? normalize(inputFile) : inputFile.map(f => normalize(f))
     const xtended = await cds.linked(await cds.load(paths, { docs: true, flavor: 'xtended' }))
     const inferred = await cds.linked(await cds.load(paths, { docs: true }))
-    return compileFromCSN({xtended, inferred}, parameters)
+    return compileFromCSN({xtended, inferred})
 }
 
 module.exports = {

package/lib/components/basedefs.js

@@ -42,6 +42,12 @@ export type DeepRequired<T> = {
     [K in keyof T]: DeepRequired<T[K]>
 } & Exclude<Required<T>, null>;
 
+const key = Symbol('key')  // to avoid .key showing up in IDE's auto-completion
+export type Key<T> = T & {[key]?: true}
+
+export type KeysOf<T> = {
+  [K in keyof T as NonNullable<T[K]> extends Key<unknown> ? K : never]-?: Key<{}>  // T[K] 
+}
 
 /**
  * Dates and timestamps are strings during runtime, so cds-typer represents them as such.

package/lib/components/inline.js

@@ -1,3 +1,4 @@
+const { configuration } = require('../config')
 const { SourceFile, Buffer } = require('../file')
 const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
@@ -94,7 +95,7 @@ class InlineDeclarationResolver {
      * @returns {'?:'|':'}
      */
     getPropertyTypeSeparator() {
-        return this.visitor.options.propertiesOptional ? '?:' : ':'
+        return configuration.propertiesOptional ? '?:' : ':'
     }
 
     /**

package/lib/components/javascript.js

@@ -3,11 +3,11 @@
 // @ts-nocheck
 const proxyAccessFunction = function (fqParts, opts = {}) {
     const { target, customProps } = { target: {}, customProps: [], ...opts }
-    const fq = fqParts.join('.')
+    const fq = fqParts.filter(p => !!p).join('.')
     return new Proxy(target, {
         get: function (target, prop) {
             if (cds.entities) {
-                target.__proto__ = cds.entities[fq]
+                target.__proto__ = cds.entities(fqParts[0])[fqParts[1]]
                 // overwrite/simplify getter after cds.entities is accessible
                 this.get = (target, prop) => target[prop]
                 return target[prop]

package/lib/components/wrappers.js

@@ -3,6 +3,20 @@
 // this was derived from baseDefinitions before, but caused a circular dependency
 const base = '__'
 
+/**
+ * Wraps type into the Key type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKey = t => `${base}.Key<${t}>`
+
+/**
+ * Wraps type into KeysOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKeysOf = t => `${base}.KeysOf<${t}>`
+
 /**
  * Wraps type into association to scalar.
  * @param {string} t - the singular type name.
@@ -86,6 +100,8 @@ const docify = doc => {
 
 module.exports = {
     createArrayOf,
+    createKey,
+    createKeysOf,
     createObjectOf,
     createPromiseOf,
     createUnionOf,

package/lib/config.js

@@ -0,0 +1,117 @@
+const cds = require('@sap/cds')
+const { camelToSnake } = require('./util')
+
+/**
+ * Makes properties of an object accessible in both camelCase and snake_case.
+ * Snake_case gets precedence over camelCase.
+ * @template T
+ * @param {T} target - The object to proxy.
+ * @returns {T} - The proxied object.
+ */
+const camelSnakeHybrid = target => {
+    // @ts-expect-error - expecting target to be of type {}, which is not T (same for following)
+    const proxy = new Proxy(target, {
+        get(target, prop) {
+            // @ts-expect-error
+            return target[camelToSnake(prop)] ?? target[prop]
+        },
+        set(target, p, v) {
+            // @ts-expect-error
+            target[camelToSnake(p)] = v
+            return true
+        }
+    })
+    // need to make sure all properties are initially available in snake_case
+    // @ts-expect-error
+    for (const [k,v] of Object.entries(target)) {
+        // @ts-expect-error
+        proxy[k] = v
+    }
+    // @ts-expect-error
+    return proxy
+}
+class Config {
+    static #defaults = {
+        propertiesOptional: true,
+        useEntitiesProxy: false,
+        inlineDeclarations: 'flat'
+    }
+
+    values = undefined
+    proxy = undefined
+
+    init () {
+        this.values = {...Config.#defaults, ...(cds.env.typer ?? {})}
+        this.proxy = camelSnakeHybrid(this.values)
+    }
+
+    constructor() {
+        // proxy around config still allows arbitrary property access:
+        // require('config').configuration.logLevel = 'warn' will work
+        // eslint-disable-next-line no-constructor-return
+        return new Proxy(this, {
+            get(target, prop) {
+                // lazy loading of cds.env
+                // if we don't do this, configuration will load cds.env whenever it is
+                // first imported anywhere (even by proxy from, say, cli.js).
+                // So we don't get to modify cds.env before that, which is important
+                // in cds-build.js.
+                // FIXME: revisit. This is horrible.
+                if (target.values === undefined) target.init()
+                return target[prop] ?? target.proxy[prop]
+            },
+            set(target, p, v) {
+                if (target.values === undefined) target.init()
+
+                // this.value, this.proxy etc should not be forwarded to the wrapped values
+                if (target[p]) {
+                    target[p] = v
+                } else {
+                    target.proxy[p] = v
+                }
+                return true
+            }
+        })
+    }
+
+    /**
+     * @param {string} key - The key to set.
+     * @param {any} value - The value to set
+     */
+    setOne (key, value) {
+        this.proxy[key] = value
+    }
+
+    /**
+     * @param {object} props - The properties to set.
+     */
+    setMany (props) {
+        for (const [k,v] of Object.entries(props)) {
+            this.proxy[k] = v
+        }
+    }
+
+    /**
+     * Resets the config value and sets all its values from another passed
+     * config object. This allows to keep the reference to the same object.
+     * @param {Config} config - Another config object to set all config entries from.
+     */
+    setFrom (config) {
+        this.values = camelSnakeHybrid({})
+        this.setMany(config.values)
+    }
+
+    clone () {
+        const res = new Config()
+        res.init()
+        res.setMany(this.values)
+        return res
+    }
+}
+
+module.exports = {
+    camelSnakeHybrid,
+    /** @type {import('./typedefs').config.Configuration} */
+    // @ts-ignore
+    configuration: new Config()
+}

package/lib/file.js

@@ -8,11 +8,11 @@ const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
 const { proxyAccessFunction } = require('./components/javascript')
 const { createObjectOf } = require('./components/wrappers')
+const { configuration } = require('./config')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
 /** @typedef {import('./typedefs').file.Namespace} Namespace */
-/** @typedef {import('./typedefs').file.FileOptions} FileOptions */
 
 class File {
     /**
@@ -109,11 +109,9 @@ class Library extends File {
 class SourceFile extends File {
     /**
      * @param {string | Path} path - path to the file
-     * @param {FileOptions} [options] - options for file output
      */
-    constructor(path, options) {
+    constructor(path) {
         super()
-        this.options = options ?? { useEntitiesProxy: false }
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
         /** @type {{[key:string]: any}} */
@@ -437,7 +435,7 @@ class SourceFile extends File {
         const namespace = this.path.asNamespace()
 
         const boilerplate = [AUTO_GEN_NOTE]
-        if (this.options.useEntitiesProxy) {
+        if (configuration.useEntitiesProxy) {
             if (namespace === '_') {
                 boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
             } else {
@@ -460,7 +458,7 @@ class SourceFile extends File {
      * @returns {{singularRhs: string, pluralRhs: string}}
      */
     #getEntityExportsRhs(singular, original) {
-        if (this.options.useEntitiesProxy) {
+        if (configuration.useEntitiesProxy) {
             const namespace = this.path.asNamespace()
             // determine the custom properties for the proxy function call
             const customProps = this.entityProxies[singular] ?? []
@@ -697,13 +695,6 @@ class FileRepository {
     /** @type {{[key:string]: SourceFile}} */
     #files = {}
 
-    /**
-     * @param {FileOptions} options - options to control file
-     */
-    constructor(options) {
-        this.options = options
-    }
-
     /**
      * @param {string} name - file name
      * @param {SourceFile} file - the file
@@ -720,7 +711,7 @@ class FileRepository {
      */
     getNamespaceFile(path) {
         const key = path instanceof Path ? path.asNamespace() : path
-        return (this.#files[key] ??= new SourceFile(path, this.options))
+        return (this.#files[key] ??= new SourceFile(path))
     }
 
     /**

package/lib/resolution/resolver.js

@@ -3,7 +3,7 @@
 const util = require('../util')
 // eslint-disable-next-line no-unused-vars
 const { Buffer, SourceFile, Path, Library } = require('../file')
-const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne } = require('../components/wrappers')
+const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne, createKey } = require('../components/wrappers')
 const { StructuredInlineDeclarationResolver } = require('../components/inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('../components/enum')
 const { isReferenceType } = require('../components/reference')
@@ -13,6 +13,7 @@ const { BuiltinResolver } = require('./builtin')
 const { LOG } = require('../logging')
 const { last } = require('../components/identifier')
 const { getPropertyModifiers } = require('../components/property')
+const { configuration } = require('../config')
 
 /** @typedef {import('../visitor').Visitor} Visitor */
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
@@ -30,7 +31,7 @@ class Resolver {
         this.visitor = visitor
 
         /** @type {BuiltinResolver} */
-        this.builtinResolver = new BuiltinResolver(visitor.options)
+        this.builtinResolver = new BuiltinResolver({ IEEE754Compatible: configuration.IEEE754Compatible })
 
         /** @type {Library[]} */
         this.libraries = [new Library(require.resolve('../../library/cds.hana.ts'))]
@@ -63,8 +64,7 @@ class Resolver {
      * @returns {boolean} whether the type is configured to be optional
      */
     isOptional(type) {
-        // TODO temporary solution to determine optional parameters. Align w/ compiler/importer.
-        return Object.keys(type).some(k => k.startsWith('@Core.OptionalParameter'))
+        return !type.notNull
     }
 
     /**
@@ -159,8 +159,8 @@ class Resolver {
         if (parts.length <= 1) return []
 
         /**
-         * @param {string} property
-         * @param {import('../typedefs').resolver.EntityCSN} entity
+         * @param {string} property - the property to check
+         * @param {import('../typedefs').resolver.EntityCSN} entity - the entity to check the property against
          */
         const isPropertyOf = (property, entity) => property && Object.hasOwn(entity?.elements ?? {}, property)
 
@@ -385,6 +385,10 @@ class Resolver {
             plural: typeName
         }
 
+        if (element.key === true) {
+            typeName = createKey(typeName)
+        }
+
         // FIXME: typeName could probably just become part of typeInfo
         return { typeName, typeInfo }
     }

package/lib/typedefs.d.ts

@@ -99,47 +99,13 @@ export module resolver {
 
 export module util {
     export type Annotations = {
-        name?: string,
+        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,
-        useEntitiesProxy: boolean,
-        jsConfigPath?: string,
-        inlineDeclarations: 'flat' | 'structured',
-        propertiesOptional: boolean,
-        IEEE754Compatible: boolean,
-    }
-
-    export type VisitorOptions = {
-        /** `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable) */
-        propertiesOptional: boolean,
-        /**
-         * `inlineDeclarations = 'structured'` -> @see {@link inline.StructuredInlineDeclarationResolver}
-         * `inlineDeclarations = 'flat'` -> @see {@link inline.FlatInlineDeclarationResolver}
-         */
-        inlineDeclarations: 'flat' | 'structured',
-        /**
-         * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects
-         */
-        useEntitiesProxy: boolean
-    }
-
     export type Inflection = {
         typeName?: string,
         singular: string,
@@ -158,9 +124,54 @@ export module visitor {
     }
 }
 
+export module config {
+    export module cli {
+        export type CLIFlags = 'version' | 'help'
+        export type ParameterSchema = {
+            [key: string]: {
+                desc: string,
+                allowed?: string[],
+                allowedHint?: string,
+                type?: 'string' | 'boolean' | 'number',
+                default?: string,
+                defaultHint?: string,
+                postprocess?: (value: string) => any,
+                camel?: string,
+                snake?: string
+            }
+        }
+
+        export type ParsedParameters = {
+            positional: string[],
+            named: { [key: keyof RuntimeParameters]: {
+                value: any,
+                isDefault: boolean,
+            } }
+        }
+    }
+
+    export type Configuration = {
+        outputDirectory: string,
+        logLevel: number,
+        /**
+         * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects
+         */
+        useEntitiesProxy: boolean,
+        jsConfigPath?: string,
+        /**
+         * `inlineDeclarations = 'structured'` -> @see {@link inline.StructuredInlineDeclarationResolver}
+         * `inlineDeclarations = 'flat'` -> @see {@link inline.FlatInlineDeclarationResolver}
+         */
+        inlineDeclarations: 'flat' | 'structured',
+        /** `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable) */
+        propertiesOptional: boolean,
+        /**
+         * `IEEE754Compatible = true` -> any cds.Decimal will become `number | string`
+         */
+        IEEE754Compatible: boolean
+    }
+}
+
 export module file {
     export type Namespace = Object<string, Buffer>
-    export type FileOptions = {
-        useEntitiesProxy: boolean
-    }
 }

package/lib/util.js

@@ -19,6 +19,16 @@ const annotations = {
     plural: ['@plural'],
 }
 
+/**
+ * Converts a camelCase string to snake_case.
+ * @param {string} camel - The camelCase string.
+ * @returns {string} - The snake_case string.
+ */
+const camelToSnake = camel => camel
+    .replace(/([a-z])([A-Z])/g, '$1_$2') // Handle camelCase
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2') // Handle sequences of uppercase letters
+    .toLowerCase()
+
 /**
  * Tries to retrieve an annotation that specifies the singular name
  * from a CSN. Valid annotations are listed in util.annotations
@@ -27,6 +37,7 @@ const annotations = {
  * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the singular annotation or undefined
  */
+// @ts-expect-error - can not use possible undefined from find as key
 const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.hasOwn(csn, a))]
 
 /**
@@ -37,6 +48,7 @@ const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.h
  * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the plural annotation or undefined
  */
+// @ts-expect-error - can not use possible undefined from find as key
 const getPluralAnnotation = csn => csn[annotations.plural.find(a => Object.hasOwn(csn, a))]
 
 /**
@@ -62,9 +74,9 @@ const unlocalize = name => {
  * @param {boolean?} stripped - if true, leading namespace will be stripped
  */
 const singular4 = (dn, stripped = false) => {
-    let n = dn.name || dn
+    let n = dn.name ?? dn
     if (stripped) {
-        n = n.match(last)[0]
+        n = n.match(last)?.[0] ?? ''
     }
     return (
         getSingularAnnotation(dn) ??
@@ -94,9 +106,9 @@ const singular4 = (dn, stripped = false) => {
  * @param {boolean} stripped - if true, leading namespace will be stripped
  */
 const plural4 = (dn, stripped) => {
-    let n = dn.name || dn
+    let n = dn.name ?? dn
     if (stripped) {
-        n = n.match(last)[0]
+        n = n.match(last)?.[0]
     }
     return (
         getPluralAnnotation(dn) ??
@@ -123,72 +135,13 @@ const deepMerge = (target, source) => {
     Object.assign(target, source)
 }
 
-/**
- * Parses command line arguments into named and positional parameters.
- * Named parameters are expected to start with a double dash (--).
- * If the next argument `B` after a named parameter `A` is not a named parameter itself,
- * `B` is used as value for `A`.
- * If `A` and `B` are both named parameters, `A` is just treated as a flag (and may receive a default value).
- * Only named parameters that occur in validFlags are allowed. Specifying named flags that are not listed there
- * 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 {{[key: string]: CommandlineFlag}} validFlags - allowed flags. May specify default values.
- * @returns {ParsedFlags}
- */
-const parseCommandlineArgs = (argv, validFlags) => {
-    const isFlag = (/** @type {string} */ arg) => arg.startsWith('--')
-    const positional = []
-    const named = {}
-
-    let i = 0
-    while (i < argv.length) {
-        let arg = argv[i]
-        if (isFlag(arg)) {
-            arg = arg.slice(2)
-            if (!(arg in validFlags)) {
-                throw new Error(`invalid named flag '${arg}'`)
-            } else {
-                const next = argv[i + 1]
-                if (next && !isFlag(next)) {
-                    named[arg] = next
-                    i++
-                } else {
-                    named[arg] = validFlags[arg].default
-                }
-
-                const { allowed, allowedHint } = validFlags[arg]
-                if (allowed && !allowed.includes(named[arg])) {
-                    throw new Error(`invalid value '${named[arg]}' for flag ${arg}. Must be one of ${(allowedHint ?? allowed.join(', '))}`)
-                }
-            }
-        } else {
-            positional.push(arg)
-        }
-        i++
-    }
-
-    const defaults = Object.entries(validFlags)
-        .filter(e => !!e[1].default)
-        .reduce((dict, [k, v]) => {
-            dict[k] = v.default
-            return dict
-        }, {})
-
-    return {
-        named: Object.assign(defaults, named),
-        positional,
-    }
-}
-
 module.exports = {
     annotations,
+    camelToSnake,
     getSingularAnnotation,
     getPluralAnnotation,
     unlocalize,
     singular4,
     plural4,
-    parseCommandlineArgs,
     deepMerge
 }

package/lib/visitor.js

@@ -8,7 +8,7 @@ const { SourceFile, FileRepository, Buffer, Path } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./resolution/resolver')
 const { LOG } = require('./logging')
-const { docify, createPromiseOf, createUnionOf } = require('./components/wrappers')
+const { docify, createPromiseOf, createUnionOf, createKeysOf } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
@@ -16,23 +16,15 @@ const { baseDefinitions } = require('./components/basedefs')
 const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
+const { configuration } = require('./config')
 
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
-/** @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters */
-/** @typedef {import('./typedefs').visitor.VisitorOptions} VisitorOptions */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
 /** @typedef {import('./typedefs').resolver.CSN} CSN */
 /** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
 /** @typedef {import('./typedefs').resolver.EnumCSN} EnumCSN */
 
-const defaults = {
-    // FIXME: add defaults for remaining parameters
-    propertiesOptional: true,
-    useEntitiesProxy: false,
-    inlineDeclarations: 'flat'
-}
-
 class Visitor {
     /**
      * Gathers all files that are supposed to be written to
@@ -46,12 +38,10 @@ class Visitor {
 
     /**
      * @param {{xtended: CSN, inferred: CSN}} csn - root CSN
-     * @param {VisitorOptions | {}} options - the options
      */
-    constructor(csn, options = {}) {
+    constructor(csn) {
         amendCSN(csn.xtended)
         propagateForeignKeys(csn.inferred)
-        this.options = { ...defaults, ...options }
         this.csn = csn
 
         /** @type {Context[]} **/
@@ -64,12 +54,10 @@ class Visitor {
         this.entityRepository = new EntityRepository(this.resolver)
 
         /** @type {FileRepository} */
-        this.fileRepository = new FileRepository(this.options)
-        // REVISIT: better way to pass options to base source file ???
-        baseDefinitions.options = this.options
+        this.fileRepository = new FileRepository()
         this.fileRepository.add(baseDefinitions.path.asNamespace(), baseDefinitions)
         this.inlineDeclarationResolver =
-            this.options.inlineDeclarations === 'structured'
+            configuration.inlineDeclarations === 'structured'
                 ? new StructuredInlineDeclarationResolver(this)
                 : new FlatInlineDeclarationResolver(this)
 
@@ -105,7 +93,13 @@ class Visitor {
                 // FIXME: references to types of entity properties may be missing from xtendend flavour (see #103)
                 // this should be revisted once we settle on a single flavour.
                 const target = this.csn.xtended.definitions[targetName] ?? this.csn.inferred.definitions[targetName]
-                this.visitEntity(name, target)
+                if (target.kind !== 'type') {
+                    // skip if the target is a property, like in:
+                    // books: Association to many Author.books ...
+                    // as this would result in a type definition that
+                    // name-clashes with the actual declaration of Author
+                    this.visitEntity(name, target)
+                }
             } else {
                 LOG.error(`Expecting an autoexposed projection within a service. Skipping ${name}`)
             }
@@ -160,6 +154,14 @@ class Visitor {
         }
     }
 
+    /**
+     * @param {Buffer} buffer - the buffer to write the keys into
+     * @param {string} clean - the clean name of the entity
+     */
+    #printStaticKeys(buffer, clean) {
+        buffer.add(`declare static readonly keys: ${createKeysOf(clean)}`)
+    }
+
     /**
      * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
      * That is, for an element A we get:
@@ -272,6 +274,8 @@ class Visitor {
                         file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
                     }
                     this.#printStaticActions(entity, buffer, ancestorInfos, file)
+                    this.#printStaticKeys(buffer, clean)
+
                 })
             }, '};') // end of generated class
         }, '}') // end of aspect
@@ -488,12 +492,13 @@ class Visitor {
         buffer.add('// event')
         // only declare classes, as their properties are not optional, so we don't have to do awkward initialisation thereof.
         buffer.addIndentedBlock(`export declare class ${entityName} {`, () => {
-            const propOpt = this.options.propertiesOptional
-            this.options.propertiesOptional = false
+            const propOpt = configuration.propertiesOptional
+            // FIXME: shouldn't need to change config here! Idea: init Visitor with .options fed from config, then manipulate that
+            configuration.propertiesOptional = false
             for (const [ename, element] of Object.entries(event.elements ?? {})) {
                 this.visitElement(ename, element, file, buffer)
             }
-            this.options.propertiesOptional = propOpt
+            configuration.propertiesOptional = propOpt
         }, '}')
     }
 

package/package.json

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