@cap-js/cds-typer 0.25.0 → 0.27.0

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 } = 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,22 +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,
-    inlineDeclarations: 'flat'
-}
-
 class Visitor {
     /**
      * Gathers all files that are supposed to be written to
@@ -45,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[]} **/
@@ -66,7 +57,7 @@ class Visitor {
         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)
 
@@ -102,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}`)
             }
@@ -148,7 +145,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 {
@@ -156,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:
@@ -168,8 +174,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,18 +262,27 @@ 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)
+                    this.#printStaticKeys(buffer, clean)
+
                 })
             }, '};') // end of generated class
         }, '}') // end of aspect
 
         // 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 +306,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 +342,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 +368,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 +381,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 +420,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 +449,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 +470,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,37 +485,44 @@ 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
         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
         }, '}')
     }
 
     /**
      * @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.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",
@@ -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"