@cap-js/cds-typer 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -4,7 +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.26.0 - TBD
+## Version 0.27.0 - TBD
+
+## Version 0.26.0 - 2024-09-11
+### Added
+- 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.
+- Apps need to provide `@cap-js/cds-types` version `0.6.4` or higher.
+- Typed methods are now generated for calls of unbound actions. Named and positional call styles are supported, e.g. `service.action({one, two})` and `service.action(one, two)`.
+- Action parameters can be optional in the named call style (`service.action({one:1, ...})`).
+- Actions for ABAP RFC modules cannot be called with positional parameters, but only with named ones. They have 'parameter categories' (import/export/changing/tables) that cannot be called in a flat order.
+- Services now have their own export (named like the service itself). The current default export is not usable in some scenarios from CommonJS modules.
+- Enums and operation parameters can have doc comments
+
 
 ## Version 0.25.0 - 2024-08-13
 ### Added
@@ -85,7 +98,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Importing an enum into a service will now generate an alias to the original enum, instead of incorrectly duplicating the definition
 - Returning entities from actions/ functions and using them as parameters will now properly use the singular inflection instead of returning an array thereof
 - Aspects are now consistently named and called in their singular form
-- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation 
+- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation
 
 ## Version 0.19.0 - 2024-03-28
 ### Added

package/README.md

@@ -9,6 +9,25 @@ Generates `.ts` files for a CDS model to receive code completion in VS Code.
 
 Exhaustive documentation can be found on [CAPire](https://cap.cloud.sap/docs/tools/cds-typer).
 
+## Known Restrictions
+
+Certain language features of CDS can not be represented in TypeScript.
+Trying to generate types for models using these features will therefore result in incorrect or broken TypeScript code.
+
+### Changing Types
+
+While the following is valid CDS, there is no TypeScript equivalent that would allow the type of an inherited property to change (TS2416).
+
+```cds
+entity A {
+  foo: Integer
+};
+
+entity B: A {
+  foo: String
+}
+```
+
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/cds-typer/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).

package/lib/cli.js

@@ -35,6 +35,11 @@ const flags = {
         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'
     },
+    useEntitiesProxy: {
+        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.'
     },
@@ -117,6 +122,7 @@ const main = async (/** @type {any} */ args) => {
         // 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',

package/lib/components/enum.js

@@ -22,7 +22,7 @@ const stringifyEnumType = kvs => [...uniqueValues(kvs)].join(' | ')
 /**
  * @param {string} key - the key of the enum
  * @param {any} value - the value of the enum
- * @param {string | import('@sap/cds').ref} enumType - the type of the enum
+ * @param {string | import('../typedefs').resolver.ref} enumType - the type of the enum
  */
 const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
 
@@ -50,10 +50,12 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
  * @param {string} name - local name of the enum, i.e. the name under which it should be created in the .ts file
  * @param {[string, string][]} kvs - list of key-value pairs
  * @param {object} options - options for printing the enum
+ * @param {string[]} doc - the enum docs
  */
-function printEnum(buffer, name, kvs, options = {}) {
+function printEnum(buffer, name, kvs, options = {}, doc=[]) {
     const opts = {...{export: true}, ...options}
     buffer.add('// enum')
+    if (opts.export) doc.forEach(d => { buffer.add(d) })
     buffer.addIndentedBlock(`${opts.export ? 'export ' : ''}const ${name} = {`, () =>
         kvs.forEach(([k, v]) => { buffer.add(`${normalise(k)}: ${v},`) })
     , '} as const;')

package/lib/components/javascript.js

@@ -0,0 +1,28 @@
+/* eslint-disable no-undef */
+// this function will be stringified as part of the generated types and is not supposed to be used internally
+// @ts-nocheck
+const proxyAccessFunction = function (fqParts, opts = {}) {
+    const { target, customProps } = { target: {}, customProps: [], ...opts }
+    const fq = fqParts.join('.')
+    return new Proxy(target, {
+        get: function (target, prop) {
+            if (cds.entities) {
+                target.__proto__ = cds.entities[fq]
+                // overwrite/simplify getter after cds.entities is accessible
+                this.get = (target, prop) => target[prop]
+                return target[prop]
+            }
+            // we already know the name so we skip the cds.entities proxy access
+            if (prop === 'name') return fq
+            // custom properties access on 'target' as well as cached _entity property access goes here
+            if (Object.hasOwn(target, prop)) return target[prop]
+            // inline enums have to be caught here for first time access, as they do not exist on the entity
+            if (customProps.includes(prop)) return target[prop]
+            // last but not least we pass the property access to cds.entities
+            throw new Error(`Property ${prop} does not exist on entity '${fq}' or cds.entities is not yet defined. Ensure the CDS runtime is fully booted before accessing properties.`)
+        }
+    })
+}.toString()
+/* eslint-enable no-undef */
+
+module.exports = { proxyAccessFunction }

package/lib/components/wrappers.js

@@ -45,6 +45,24 @@ const createArrayOf = t => `Array<${t}>`
  */
 const createObjectOf = t => `{${t}}`
 
+/**
+ * Wraps types into a union type string
+ * @param {string[]} types - an array of types
+ * @returns {string}
+ */
+const createUnionOf = (...types) => types.join(' | ')
+
+/**
+ * Wraps type into a promise
+ * @param {string} t - the type to wrap.
+ * @returns {string}
+ * @example
+ * ```js
+ * createPromiseOf('string') // -> 'Promise<string>'
+ * ```
+ */
+const createPromiseOf = t => `Promise<${t}>`
+
 /**
  * Wraps type into a deep require (removes all posibilities of undefined recursively).
  * @param {string} t - the singular type name.
@@ -59,13 +77,18 @@ const deepRequire = (t, lookup = '') => `${base}.DeepRequired<${t}>${lookup}`
  * @returns {string[]} an array of lines wrapped in doc format. The result is not
  *          concatenated to be properly indented by `buffer.add(...)`.
  */
-const docify = doc => doc
-    ? ['/**'].concat(doc.split('\n').map(line => `* ${line}`)).concat(['*/'])
-    : []
+const docify = doc => {
+    if (!doc) return []
+    const lines = doc.split(/\r?\n/).map(l => l.trim().replaceAll('*/', '*\\/')) // mask any */ with *\/
+    if (lines.length === 1) return [`/** ${lines[0]} */`] // one-line doc
+    return ['/**'].concat(lines.map(line => `* ${line}`)).concat(['*/'])
+}
 
 module.exports = {
     createArrayOf,
     createObjectOf,
+    createPromiseOf,
+    createUnionOf,
     createToOneAssociation,
     createToManyAssociation,
     createCompositionOfOne,

package/lib/file.js

@@ -6,11 +6,13 @@ const { readFileSync } = require('fs')
 const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = require('./components/enum')
 const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
+const { proxyAccessFunction } = require('./components/javascript')
 const { createObjectOf } = require('./components/wrappers')
 
 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 {
     /**
@@ -107,9 +109,11 @@ 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) {
+    constructor(path, options) {
         super()
+        this.options = options ?? { useEntitiesProxy: false }
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
         /** @type {{[key:string]: any}} */
@@ -140,50 +144,64 @@ class SourceFile extends File {
         this.inflections = []
         /** @type {{ buffer: Buffer, names: string[]}} */
         this.services = { buffer: new Buffer(), names: [] }
+        /** @type {Record<string,string[]>} */
+        this.entityProxies = {}
     }
 
     /**
      * Stringifies a lambda expression.
      * @param {object} options - options
      * @param {string} options.name - name of the lambda
-     * @param {[string, string][]} [options.parameters] - list of parameters, passed as [name, type] pairs
+     * @param {import('./typedefs').visitor.ParamInfo[]} [options.parameters] - list of parameters, passed as [name, modifier, type, doc] pairs
      * @param {string} [options.returns] - the return type of the function
      * @param {'action' | 'function'} options.kind - kind of the lambda
      * @param {string} [options.initialiser] - the initialiser expression
      * @param {boolean} [options.isStatic] - whether the lambda is static
+     * @param {{positional?: boolean, named?: boolean}} [options.callStyles] - whether to generate positional and/or named call styles
+     * @param {string[]?} [options.doc] - documentation for the operation
      * @returns {string} the stringified lambda
      * @example
      * ```js
      * // note: these samples are actually simplified! See below.
-     * stringifyLambda({parameters: [['p','T']]})  // f: { (p: T): any, ... }
-     * stringifyLambda({name: 'f', parameters: [['p','T']]})  // f: { (p: T) => any, ...  }
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // f: { (p: T) => number, ...  }
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number', initialiser: '_ => 42'})  // f: { (p: T): string = _ => 42, ...  }
+     * stringifyLambda({parameters: [['p','','T']]})  // f: { (p: T): any, ... }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}]})  // f: { (p: T) => any, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',modifier:'?',type:'T',doc:'/** doc *\/'}], returns: 'number'})  // /** doc *\/f?: { (p: T) => number, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number', initialiser: '_ => 42'})  // f?: { (p: T): string = _ => 42, ...  }
      * ```
      *
-     * The generated string will not be just the signature of the function. Instead, it will be an object offering a callable signature.
+     * The generated string will not be just the signature of the function. Instead, it will be an object offering callable signature(s).
      * On top of that, it will also expose a property `__parameters`, which is an object reflecting the functions parameters.
      * 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 } }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
      * ```
      */
-    static stringifyLambda({name, parameters=[], returns='any', initialiser, isStatic=false, kind}) {
-        const parameterTypes = parameters.map(([n, t]) => `${normalise(n)}: ${t}`).join(', ')
+    static stringifyLambda({name, parameters=[], returns='any', kind, initialiser, isStatic=false, callStyles={positional:true, named:true}, doc}) {
+        let docStr = doc?.length ? doc.join('\n')+'\n' : ''
+        const parameterTypes = parameters.map(({name, modifier, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}${modifier}: ${type}`).join(', ')
         const parameterTypeAsObject = parameterTypes.length
             ? createObjectOf(parameterTypes)
             : empty
-        const callableSignature = `(${parameterTypes}): ${returns}`
+        const callableSignatures = []
+        if (callStyles.positional) {
+            const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}: ${type}`).join(', ') // must not include ? modifiers
+            callableSignatures.push(`// positional\n${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
+        }
+        if (callStyles.named) {
+            const parameterNames = createObjectOf(parameters.map(({name}) => normalise(name)).join(', '))
+            callableSignatures.push(`// named\n${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
+        }
+        if (callableSignatures.length === 0) throw new Error('At least one call style must be specified')
         let prefix = name ? `${normalise(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
         const kindDef = kind ? `, kind: '${kind}'` : ''
         const suffix = initialiser ? ` = ${initialiser}` : ''
-        const lambda = `{ ${callableSignature}, __parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
+        const lambda = `{\n${callableSignatures.join('\n')}, \n// metadata (do not use)\n__parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
         return prefix + lambda + suffix
     }
 
@@ -203,13 +221,16 @@ 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 {[string, string][]} parameters - list of parameters, passed as [name, type] pairs
+     * @param {import('./typedefs').visitor.ParamInfo[]} parameters - list of parameters, passed as [name, modifier, type] tuple
      * @param {string} returns - the return type of the function
      * @param {'function' | 'action'} kind - kind of the node
+     * @param {string[]} doc - documentation for the function
+     * @param {{positional?: boolean, named?: boolean}} callStyles - how the operation can be called
      */
-    addOperation(name, parameters, returns, kind) {
-        //this.operations.buffer.add("// operation")
-        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind})};`)
+    addOperation(name, parameters, returns, kind, doc, callStyles) {
+        // this.operations.buffer.add(`// ${kind}`)
+        if (doc) this.operations.buffer.add(doc.join('\n')) // docs shows up on action provider side: `.on(action,...)`
+        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})};`)
         this.operations.names.push(name)
     }
 
@@ -239,10 +260,11 @@ class SourceFile extends 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[]} doc - the enum docs
      */
-    addEnum(fq, name, kvs) {
+    addEnum(fq, name, kvs, doc) {
         this.enums.data.push({ name, fq, kvs })
-        printEnum(this.enums.buffer, name, kvs)
+        printEnum(this.enums.buffer, name, kvs, {}, doc)
     }
 
     /**
@@ -251,6 +273,7 @@ class SourceFile extends File {
      * @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[]} doc - the enum docs
      *  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
@@ -274,14 +297,16 @@ class SourceFile extends File {
      * }
      * ```
      */
-    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs) {
+    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs, doc=[]) {
         this.enums.data.push({
             name: `${entityCleanName}.${propertyName}`,
             property: propertyName,
             kvs,
             fq: `${entityCleanName}.${propertyName}`
         })
-        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false})
+        const entityProxy = this.entityProxies[entityCleanName] ?? (this.entityProxies[entityCleanName] = [])
+        entityProxy.push(propertyName)
+        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false}, doc)
     }
 
     /**
@@ -363,11 +388,16 @@ class SourceFile extends File {
      */
     getImports() {
         const buffer = new Buffer()
+        if (this.services.names.length) {
+            // currently only needed to extend cds.Service and would trigger unused-variable-errors in strict configs
+            buffer.add('import cds from \'@sap/cds\'') // TODO should go to visitor#printService, but can't express this as Path
+        }
         for (const imp of Object.values(this.imports)) {
             if (!imp.isCwd(this.path.asDirectory())) {
                 buffer.add(`import * as ${imp.asIdentifier()} from '${imp.asDirectory({relative: this.path.asDirectory()})}';`)
             }
         }
+        buffer.add('') // empty line after imports
         return buffer
     }
 
@@ -394,31 +424,92 @@ class SourceFile extends File {
             namespaces.join()  // needs to be after classes for possible declaration merging
         ].filter(Boolean).join('\n')
     }
+    #getEntityProxyFunctionExport() {
+        return `module.exports.createEntityProxy = ${proxyAccessFunction}`
+    }
+    /**
+     * Returns boilerplate code for `index.js` files
+     * - `useEntitiesProxy = true` -> import `createEntityProxy` function for entity proxy
+     * - `useEntitiesProxy = false` -> retrieve entities via `cds.entities(namespace)`
+     * @returns {string[]}
+     */
+    #getJSExportBoilerplate() {
+        const namespace = this.path.asNamespace()
 
+        const boilerplate = [AUTO_GEN_NOTE]
+        if (this.options.useEntitiesProxy) {
+            if (namespace === '_') {
+                boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
+            } else {
+                boilerplate.push(`const { createEntityProxy } = require('${new Path(['_']).asDirectory({relative: this.path.asDirectory()})}')`)
+            }
+        } else {
+            boilerplate.push(
+                'const cds = require(\'@sap/cds\')',
+                `const csn = cds.entities('${namespace}')`
+            )
+        }
+        return boilerplate
+    }
+    /**
+     * Returns RHS for entity `module.exports` assignments
+     * - `useEntitiesProxy = true` -> use function calls to create `Proxy` objects
+     * - `useEntitiesProxy = false` -> access entity from CSN directly
+     * @param {string} singular - singular name of entity
+     * @param {string} original - original name of entity
+     * @returns {{singularRhs: string, pluralRhs: string}}
+     */
+    #getEntityExportsRhs(singular, original) {
+        if (this.options.useEntitiesProxy) {
+            const namespace = this.path.asNamespace()
+            // determine the custom properties for the proxy function call
+            const customProps = this.entityProxies[singular] ?? []
+            let customPropsStr = customProps.length ? `, customProps: ${JSON.stringify(customProps)}` : ''
+
+            return {
+                singularRhs: `createEntityProxy(['${namespace}', '${original}'], { target: { is_singular: true }${customPropsStr} })`,
+                pluralRhs: `createEntityProxy(['${namespace}', '${original}'])`,
+            }
+        } else {
+            return {
+                singularRhs: `{ is_singular: true, __proto__: csn.${original} }`,
+                pluralRhs: `csn.${original}`
+            }
+        }
+    }
     toJSExports() {
-        return [AUTO_GEN_NOTE, 'const cds = require(\'@sap/cds\')', `const csn = cds.entities('${this.path.asNamespace()}')`] // boilerplate
+        return this.#getJSExportBoilerplate() // boilerplate
             .concat(
                 // FIXME: move stringification of service into own module
-                this.services.names.map(name => `module.exports = { name: '${name}' }`))  // there should be only one
+                this.services.names.flatMap(name => {
+                    const nameSimple = name.split('.').pop()
+                    return [
+                        '// service',
+                        `const ${nameSimple} = { name: '${name}' }`,
+                        `module.exports = ${nameSimple}`, // there should be only one and must be the first
+                        `module.exports.${nameSimple} = ${nameSimple}`
+                    ]
+                })
+            )
             .concat(this.inflections
             // sorting the entries based on the number of dots in their singular.
             // that makes sure we have defined all parent namespaces before adding subclasses to them e.g.:
             // "module.exports.Books" is defined before "module.exports.Books.text"
                 .sort(([a], [b]) => a.split('.').length - b.split('.').length)
                 .flatMap(([singular, plural, original]) => {
-                    const exports = [`module.exports.${singular} = { is_singular: true, __proto__: csn.${original} }`]
+                    const { singularRhs, pluralRhs } = this.#getEntityExportsRhs(singular, original)
+
+                    const exports = [`// ${original}`, `module.exports.${singular} = ${singularRhs}`]
                     if (!/Array<.*>/.test(plural) && plural !== original) {
                         // FIXME: this is a hack to support CDS types that will produce "Array<MyType>" as plural, which we do not want as export in the index.js files
-                        exports.push(`module.exports.${plural} = csn.${original}`)
+                        exports.push(`module.exports.${plural} = ${pluralRhs}`)
                     }
                     // FIXME: we currently produce at most 3 entries.
                     // This could be an issue when the user re-used the original name in a @singular/@plural annotation.
                     // Seems unlikely, but we have to eliminate the original entry if users start running into this.
                     if (singular !== original) {
                         // do not do the is_singular spiel if the original name is used for the plural
-                        const rhs = plural === original
-                            ? `csn.${original}`
-                            : `{ is_singular: true, __proto__: csn.${original} }`
+                        const rhs = plural === original ? pluralRhs : singularRhs
                         exports.push(`module.exports.${original} = ${rhs}`)
                     }
                     return exports
@@ -606,6 +697,13 @@ 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
@@ -622,7 +720,7 @@ class FileRepository {
      */
     getNamespaceFile(path) {
         const key = path instanceof Path ? path.asNamespace() : path
-        return (this.#files[key] ??= new SourceFile(path))
+        return (this.#files[key] ??= new SourceFile(path, this.options))
     }
 
     /**

package/lib/resolution/resolver.js

@@ -58,6 +58,15 @@ class Resolver {
         return this.existsInCsn(fq) || Boolean(this.builtinResolver.resolveBuiltin(fq))
     }
 
+    /**
+     * @param {EntityCSN} type - a CSN type
+     * @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'))
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}

package/lib/typedefs.d.ts

@@ -8,6 +8,7 @@ export module resolver {
 
     export type EntityCSN = {
         actions?: OperationCSN[],
+        operations?: OperationCSN[],
         cardinality?: { max?: '*' | string }
         compositions?: { target: string }[]
         doc?: string,
@@ -118,6 +119,7 @@ export module visitor {
     export type CompileParameters = {
         outputDirectory: string,
         logLevel: number,
+        useEntitiesProxy: boolean,
         jsConfigPath?: string,
         inlineDeclarations: 'flat' | 'structured',
         propertiesOptional: boolean,
@@ -132,6 +134,10 @@ export module visitor {
          * `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 = {
@@ -143,8 +149,18 @@ export module visitor {
     export type Context = {
         entity: string
     }
+
+    export type ParamInfo = {
+        name: string,
+        modifier: '' | '?',
+        type: string,
+        doc?: string
+    }
 }
 
 export module file {
     export type Namespace = Object<string, Buffer>
+    export type FileOptions = {
+        useEntitiesProxy: boolean
+    }
 }

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 } = require('./components/wrappers')
+const { docify, createPromiseOf, createUnionOf } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
@@ -29,6 +29,7 @@ const { getPropertyModifiers } = require('./components/property')
 const defaults = {
     // FIXME: add defaults for remaining parameters
     propertiesOptional: true,
+    useEntitiesProxy: false,
     inlineDeclarations: 'flat'
 }
 
@@ -63,7 +64,9 @@ class Visitor {
         this.entityRepository = new EntityRepository(this.resolver)
 
         /** @type {FileRepository} */
-        this.fileRepository = new FileRepository()
+        this.fileRepository = new FileRepository(this.options)
+        // REVISIT: better way to pass options to base source file ???
+        baseDefinitions.options = this.options
         this.fileRepository.add(baseDefinitions.path.asNamespace(), baseDefinitions)
         this.inlineDeclarationResolver =
             this.options.inlineDeclarations === 'structured'
@@ -148,7 +151,8 @@ class Visitor {
                     returns: action.returns
                         ? this.resolver.resolveAndRequire(action.returns, file).typeName
                         : 'any',
-                    kind: action.kind
+                    kind: action.kind,
+                    doc: docify(action.doc)
                 })), '}'
             ) // end of actions
         } else {
@@ -168,8 +172,7 @@ class Visitor {
      * @param {{cleanName?: string}} options - additional options
      */
     #aspectify(fq, entity, buffer, options = {}) {
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve entity ${fq}`)
+        const info = this.entityRepository.getByFqOrThrow(fq)
         const clean = options?.cleanName ?? info.withoutNamespace
         const { namespace } = info
         const file = this.fileRepository.getNamespaceFile(namespace)
@@ -257,10 +260,16 @@ class Visitor {
                     }
                 }
 
+                if ('kind' in entity) {
+                    buffer.addIndented([`static readonly kind: 'entity' | 'type' | 'aspect' = '${entity.kind}';`])
+                }
+
                 buffer.addIndented(() => {
                     for (const e of enums) {
+                        const eDoc = docify(e.doc)
+                        eDoc.forEach(d => { buffer.add(d) })
                         buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
-                        file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}))
+                        file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
                     }
                     this.#printStaticActions(entity, buffer, ancestorInfos, file)
                 })
@@ -269,6 +278,7 @@ class Visitor {
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
+        docify(entity.doc).forEach(d => { buffer.add(d) })
         buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(clean, entity).join('\n')}}`)
         this.contexts.pop()
     }
@@ -292,9 +302,7 @@ class Visitor {
          * @param {string} content - the content to set the name property to
          */
         const overrideNameProperty = (clazz, content) => `Object.defineProperty(${clazz}, 'name', { value: '${content}' })`
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve entity ${fq}`)
-        const { namespace: ns, entityName: clean, inflection } = info
+        const { namespace: ns, entityName: clean, inflection } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(ns)
         let { singular, plural } = inflection
 
@@ -330,7 +338,6 @@ class Visitor {
         // which would not be possible while already in singular form, as "Book.text" could not be resolved in CSN.
         // edge case: @singular annotation present. singular4 will take care of that.
         file.addInflection(util.singular4(entity, true), plural, clean)
-        docify(entity.doc).forEach(d => { buffer.add(d) })
 
         // in case of projections `entity` is empty -> retrieve from inferred csn where the actual properties are rolled out
         const target = isProjection(entity) || isView(entity)
@@ -357,6 +364,7 @@ class Visitor {
             // so it can get passed as value to CQL functions.
             const additionalProperties = this.#staticClassContents(singular, entity)
             additionalProperties.push('$count?: number')
+            docify(entity.doc).forEach(d => { buffer.add(d) })
             buffer.add(`export class ${plural} extends Array<${singular}> {${additionalProperties.join('\n')}}`)
             buffer.add(overrideNameProperty(plural, entity.name))
         }
@@ -369,18 +377,18 @@ class Visitor {
      * Also filters out parameters that indicate a binding parameter ({@link https://cap.cloud.sap/docs/releases/jan23#simplified-syntax-for-binding-parameters}).
      * @param {{[key:string]: EntityCSN}} params - parameter list as found in CSN.
      * @param {SourceFile} file - source file relative to which the parameter types should be resolved.
-     * @returns {[string, string][]} pair of names and types.
+     * @returns {import('./typedefs').visitor.ParamInfo[]} tuple of name, modifier, type and doc.
      */
     #stringifyFunctionParams(params, file) {
-        return params
-            ? Object.entries(params)
-                // filter params of type '[many] $self', as they are not to be part of the implementation
-                .filter(([, type]) => type?.type !== '$self' && type.items?.type !== '$self')
-                .map(([name, type]) => [
-                    name,
-                    this.#stringifyFunctionParamType(type, file)
-                ])
-            : []
+        return Object.entries(params ?? {})
+            // filter params of type '[many] $self', as they are not to be part of the implementation
+            .filter(([, type]) => type?.type !== '$self' && type.items?.type !== '$self')
+            .map(([name, type]) => ({
+                name,
+                modifier: this.resolver.isOptional(type) ? '?' : '',
+                type: this.#stringifyFunctionParamType(type, file),
+                doc: docify(type.doc).join('\n'),
+            }))
     }
 
     /**
@@ -408,21 +416,27 @@ class Visitor {
      */
     #printOperation(fq, operation, kind) {
         LOG.debug(`Printing operation ${fq}:\n${JSON.stringify(operation, null, 2)}`)
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve operation ${fq}`)
-        const { namespace } = info
+        const { namespace } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
         const params = this.#stringifyFunctionParams(operation.params, file)
         const returnType = operation.returns
             ? this.resolver.resolveAndRequire(operation.returns, file)
             : { typeName: 'void', typeInfo: { plainName: 'void', isArray: false, inflection: { singular: 'void', plural: 'void' } } }
-        const returns = this.inlineDeclarationResolver.getPropertyDatatype(
+        let returns = this.inlineDeclarationResolver.getPropertyDatatype(
             returnType,
             returnType.typeInfo.isArray
                 ? returnType.typeName
                 : returnType.typeInfo.inflection.singular
         )
-        file.addOperation(last(fq), params, returns, kind)
+        if (operation.returns) {
+            // operation results may be a Promise
+            returns = createUnionOf(createPromiseOf(returns), returns)
+        }
+        // Actions for ABAP RFC modules have 'parameter categories' (import/export/changing/tables) that cannot be called in a flat order.
+        // Prevent positional call style there.
+        // TODO find a better way to detect ABAP RFC actions
+        const isRFC = Object.values(operation.params ?? {}).some(p => Object.keys(p).some(k => k.startsWith('@RFC')))
+        file.addOperation(last(fq), params, returns, kind, docify(operation.doc), {named: true, positional: !isRFC})
     }
 
     /**
@@ -431,15 +445,13 @@ class Visitor {
      */
     #printType(fq, type) {
         LOG.debug(`Printing type ${fq}:\n${JSON.stringify(type, null, 2)}`)
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve type ${fq}`)
-        const { namespace, entityName } = info
+        const { namespace, entityName } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
         // skip references to enums.
         // "Base" enums will always have a builtin type (don't skip those).
         // A type referencing an enum E will be considered an enum itself and have .type === E (skip).
         if (isEnum(type) && !isReferenceType(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)) {
-            file.addEnum(fq, entityName, csnToEnumPairs(type))
+            file.addEnum(fq, entityName, csnToEnumPairs(type), docify(type.doc))
         } else {
             const isEnumReference = typeof type.type === 'string' && isEnum(this.csn.inferred.definitions[type?.type])
             // alias
@@ -454,9 +466,7 @@ class Visitor {
      */
     #printAspect(fq, aspect) {
         LOG.debug(`Printing aspect ${fq}`)
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve aspect ${fq}`)
-        const { namespace, entityName, inflection } = info
+        const { namespace, entityName, inflection } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
         // aspects are technically classes and can therefore be added to the list of defined classes.
         // Still, when using them as mixins for a class, they need to already be defined.
@@ -471,10 +481,7 @@ class Visitor {
      * @param {EntityCSN} event - CSN
      */
     #printEvent(fq, event) {
-        LOG.debug(`Printing event ${fq}`)
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve event ${fq}`)
-        const { namespace, entityName } = info
+        const { namespace, entityName } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
         file.addEvent(entityName, fq)
         const buffer = file.events.buffer
@@ -492,16 +499,25 @@ class Visitor {
 
     /**
      * @param {string} fq - fully qualified name of the service
-     * @param {EntityCSN} service - CSN
+     * @param {import('./typedefs').resolver.EntityCSN} service - CSN
      */
     #printService(fq, service) {
         LOG.debug(`Printing service ${fq}:\n${JSON.stringify(service, null, 2)}`)
-        const info = this.entityRepository.getByFq(fq)
-        if (!info) throw new Error(`could not resolve service ${fq}`)
-        const { namespace } = info
+        const { namespace } = this.entityRepository.getByFqOrThrow(fq)
         const file = this.fileRepository.getNamespaceFile(namespace)
-        // service.name is clean of namespace
-        file.services.buffer.add(`export default { name: '${service.name}' }`)
+        const buffer = file.services.buffer
+        const serviceNameSimple = service.name.split('.').pop()
+
+        docify(service.doc).forEach(d => { buffer.add(d) })
+        // file.addImport(new Path(['cds'], '')) TODO make sap/cds import work
+        buffer.addIndentedBlock(`export class ${serviceNameSimple} extends cds.Service {`, () => {
+            Object.entries(service.operations ?? {}).forEach(([name, {doc}]) => {
+                docify(doc).forEach(d => { buffer.add(d) })
+                buffer.add(`declare ${name}: typeof ${name}`)
+            })
+        }, '}')
+        buffer.add(`export default ${serviceNameSimple}`)
+        buffer.add('')
         file.addService(service.name)
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.25.0",
+  "version": "0.26.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",
@@ -40,15 +40,17 @@
   "bin": {
     "cds-typer": "./lib/cli.js"
   },
-  "dependencies": {
-    "@sap/cds": ">=7.7"
+  "peerDependencies": {
+    "@cap-js/cds-types": ">=0.6.4",
+    "@sap/cds": ">=8"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin-js": "^1.6.3",
-    "@cap-js/cds-types": ">=0.6",
+    "@cap-js/cds-types": "^0",
+    "@sap/cds": "^8",
+    "@stylistic/eslint-plugin-js": "^2.7.2",
     "acorn": "^8.10.0",
     "eslint": "^9",
-    "eslint-plugin-jsdoc": "^48.2.7",
+    "eslint-plugin-jsdoc": "^50.2.2",
     "globals": "^15.0.0",
     "jest": "^29",
     "typescript": ">=4.6.4"