@cap-js/cds-typer 0.28.1 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## Version 0.30.0 - TBD
+
+## Version 0.29.0 - 2024-11-20
+### Added
+- [breaking] cds-typer now tries to automatically detect whether it has to generate ESM or CommonJS in the emitted _index.js_ files. This behaviour can be overridden via the `--targetModuleType` option. _If you rely on these generated index.js files to be CJS despite your project being of ESM type, you need to manually tell cds-typer to generate CJS files!_ 
+
+### Fixed
+- The static `.keys` property now properly reels in key types from inherited classes.
+
 ## Version 0.28.1 - 2024-11-07
 ### Fixed
 - `cds build` no longer fails on Windows with an `EINVAL` error.

package/lib/cli.js

@@ -190,7 +190,12 @@ const flags = enrichFlagSchema({
     IEEE754Compatible: parameterTypes.boolean({
         desc: `If set to true, floating point properties are generated${EOL}as IEEE754 compatible '(number | string)' instead of 'number'.`,
         default: 'false'
-    })
+    }),
+    targetModuleType: {
+        desc: `Output format for generated .js files.${EOL}Setting it to auto tries to derive the module type from${EOL}the package.json and falls back to CJS.`,
+        allowed: ['esm', 'cjs', 'auto'],
+        default: 'auto'
+    }
 })
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'

package/lib/components/inline.js

@@ -1,7 +1,7 @@
 const { configuration } = require('../config')
 const { SourceFile, Buffer } = require('../file')
 const { normalise } = require('./identifier')
-const { docify } = require('./wrappers')
+const { docify } = require('../printers/wrappers')
 
 /** @typedef {import('../resolution/resolver').TypeResolveInfo} TypeResolveInfo */
 /** @typedef {import('../resolution/resolver').TypeResolveOptions} TypeResolverOptions */

package/lib/config.js

@@ -1,5 +1,6 @@
 const cds = require('@sap/cds')
-const { camelToSnake } = require('./util')
+const { camelToSnake, getProjectTargetType } = require('./util')
+const { LOG } = require('./logging')
 
 /**
  * Makes properties of an object accessible in both camelCase and snake_case.
@@ -35,7 +36,8 @@ class Config {
         propertiesOptional: true,
         useEntitiesProxy: false,
         inlineDeclarations: 'flat',
-        outputDirectory: '.'
+        outputDirectory: '.',
+        targetModuleType: 'auto'
     }
 
     values = undefined
@@ -44,6 +46,16 @@ class Config {
     init () {
         this.values = {...Config.#defaults, ...(cds.env.typer ?? {})}
         this.proxy = camelSnakeHybrid(this.values)
+        if (this.values.targetModuleType === 'auto') {
+            const type = getProjectTargetType(cds.root)
+            if (type) {
+                LOG.info(`automatically detected module type '${type}' in ${cds.root}`)
+                this.values.targetModuleType = type
+            } else {
+                LOG.warn(`target module type was set to 'auto', but could not detect module type in ${cds.root}. Falling back to cjs`)
+                this.values.targetModuleType = 'cjs'
+            }
+        }
     }
 
     constructor() {

package/lib/file.js

@@ -7,8 +7,10 @@ const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = req
 const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
 const { proxyAccessFunction } = require('./components/javascript')
-const { createObjectOf } = require('./components/wrappers')
+const { createObjectOf, stringIdent } = require('./printers/wrappers')
 const { configuration } = require('./config')
+const { CJSPrinter, ESMPrinter } = require('./printers/javascript')
+const { getProjectTargetType } = require('./util')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
@@ -144,6 +146,10 @@ class SourceFile extends File {
         this.services = { buffer: new Buffer(), names: [] }
         /** @type {Record<string,string[]>} */
         this.entityProxies = {}
+        /** @type {import('../lib/printers/javascript').Printer} */
+        this.jsPrinter = configuration.targetModuleType === 'esm'
+            ? new ESMPrinter()
+            : new CJSPrinter()
     }
 
     /**
@@ -428,7 +434,7 @@ class SourceFile extends File {
         ].filter(Boolean).join('\n')
     }
     #getEntityProxyFunctionExport() {
-        return `module.exports.createEntityProxy = ${proxyAccessFunction}`
+        return this.jsPrinter.printExport('createEntityProxy', proxyAccessFunction)
     }
     /**
      * Returns boilerplate code for `index.js` files
@@ -438,18 +444,23 @@ class SourceFile extends File {
      */
     #getJSExportBoilerplate() {
         const namespace = this.path.asNamespace()
-
+        const jsp = this.jsPrinter
         const boilerplate = [AUTO_GEN_NOTE]
         if (configuration.useEntitiesProxy) {
             if (namespace === '_') {
-                boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
+                boilerplate.push(jsp.printImport('cds', '@sap/cds'), this.#getEntityProxyFunctionExport())
             } else {
-                boilerplate.push(`const { createEntityProxy } = require('${new Path(['_']).asDirectory({relative: this.path.asDirectory()})}')`)
+                boilerplate.push(
+                    jsp.printDeconstructedImport(
+                        ['createEntityProxy'],
+                        new Path(['_']).asDirectory({ relative: this.path.asDirectory() })
+                    )
+                )
             }
         } else {
             boilerplate.push(
-                'const cds = require(\'@sap/cds\')',
-                `const csn = cds.entities('${namespace}')`
+                jsp.printImport('cds', '@sap/cds'),
+                jsp.printConstant('csn', `cds.entities('${namespace}')`)
             )
         }
         return boilerplate
@@ -480,18 +491,32 @@ class SourceFile extends File {
             }
         }
     }
+
     toJSExports() {
+        const jsp = this.jsPrinter
         return this.#getJSExportBoilerplate() // boilerplate
             .concat(
                 // FIXME: move stringification of service into own module
                 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}`
+                    const nameSimple = /** @type {string} */(name.split('.').pop())
+                    const service = [
+                        jsp.printSingleLineComment('service'),
+                        jsp.printConstant(nameSimple, `{ name: '${name}' }`),
+                        jsp.printDefaultExport(nameSimple), // there should be only one and must be the first
                     ]
+                    if (jsp instanceof CJSPrinter) {
+                        // unfortunately, we have to add a tiny bit of special logic for CJS, where we get:
+                        //
+                        // module.exports = FooService
+                        // module.exports.FooService = FooService
+                        //
+                        // which, in ESM, would amount to:
+                        //
+                        // export const FooService
+                        // default export FooService = FooService // <- duplicate identifier
+                        service.push(jsp.printExport(nameSimple, nameSimple))
+                    }
+                    return service
                 })
             )
             .concat(this.inflections
@@ -502,10 +527,13 @@ class SourceFile extends File {
                 .flatMap(([singular, plural, original]) => {
                     const { singularRhs, pluralRhs } = this.#getEntityExportsRhs(singular, original)
 
-                    const exports = [`// ${original}`, `module.exports.${singular} = ${singularRhs}`]
+                    const exports = [
+                        jsp.printSingleLineComment(original),
+                        jsp.printExport(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} = ${pluralRhs}`)
+                        exports.push(jsp.printExport(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.
@@ -513,16 +541,16 @@ class SourceFile extends File {
                     if (singular !== original) {
                         // do not do the is_singular spiel if the original name is used for the plural
                         const rhs = plural === original ? pluralRhs : singularRhs
-                        exports.push(`module.exports.${original} = ${rhs}`)
+                        exports.push(jsp.printExport(original, rhs))
                     }
                     return exports
                 })
             ) // singular -> plural aliases
-            .concat(['// events'])
-            .concat(this.events.fqs.map(({fq, name}) => `module.exports.${name} = '${fq}'`))
-            .concat(['// actions'])
-            .concat(this.operations.names.map(name => `module.exports.${name} = '${name}'`))
-            .concat(['// enums'])
+            .concat(jsp.printSingleLineComment('events'))
+            .concat(this.events.fqs.map(({fq, name}) => jsp.printExport(name, stringIdent(fq))))
+            .concat(jsp.printSingleLineComment('actions'))
+            .concat(this.operations.names.map(name => jsp.printExport(name, stringIdent(name))))
+            .concat(jsp.printSingleLineComment('enums'))
             .concat(this.enums.data.map(({name, kvs}) => stringifyEnumImplementation(name, kvs)))
             .join('\n') + '\n'
     }
@@ -555,6 +583,15 @@ class Buffer {
         this.closed = false
     }
 
+    /**
+     * @returns {Buffer} an empty Buffer that starts at this Buffer's current indentation.
+     */
+    createSubBuffer() {
+        const sub = new Buffer(this.indentation)
+        sub.currentIndent = this.currentIndent
+        return sub
+    }
+
     /**
      * Indents by the predefined spacing.
      */

package/lib/printers/javascript.js

@@ -0,0 +1,131 @@
+class JavaScriptPrinter {
+    /**
+     * @param {string} text - comment text
+     */
+    printSingleLineComment (text) {
+        return `// ${text}`
+    }
+
+    /**
+     * @param {string} name - name of the constant
+     * @param {string} value - initial assignment to the constant
+     */
+    printConstant (name, value) {
+        return `const ${name} = ${value}`
+    }
+
+    /**
+     * @abstract
+     * @param {string} alias - what the import should be known as within the importing file
+     * @param {string} from - the package/ location to import from 
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printImport (alias, from) {
+        throw Error('not implemented')
+    }
+
+    /**
+     * @abstract
+     * @param {string[]} imports - the deconstructed elements
+     * @param {string} from - the package/ location to import from
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printDeconstructedImport (imports, from) {
+        throw Error('not implemented')
+    }
+
+    /**
+     * @abstract
+     * @param {string} name - name the export should be known as
+     * @param {string} value - the value of the export
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printExport (name, value) {
+        throw Error('not implemented')
+    }
+
+    /**
+     * @abstract
+     * @param {string} value - the value of the default export
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printDefaultExport (value) {
+        throw Error('not implemented')
+    }
+
+    /**
+     * @abstract
+     * @param {string} file - the file name without extension
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    nameFile (file) {
+        throw Error('not implemented')
+    }
+}
+
+class ESMPrinter extends JavaScriptPrinter {
+    /** @type {JavaScriptPrinter['printImport']} */
+    printImport (alias, from) {
+        return `import * as ${alias} from '${from}'`
+    }
+
+    /** @type {JavaScriptPrinter['printDeconstructedImport']} */
+    printDeconstructedImport (imports, from) {
+        return `import { ${imports.join(', ')} } from '${from}'`
+    }
+
+    /** @type {JavaScriptPrinter['printExport']} */
+    printExport (name, value) {
+        return `export const ${name} = ${value}`
+    }
+
+    /** @type {JavaScriptPrinter['printDefaultExport']} */
+    printDefaultExport (value) {
+        return `export default ${value}`
+    }
+
+    /** @type {JavaScriptPrinter['nameFile']} */
+    nameFile (file) {
+        return `${file}.mjs`
+    }
+}
+
+class CJSPrinter extends JavaScriptPrinter {
+    /** @type {JavaScriptPrinter['printImport']} */
+    printImport (alias, from) {
+        return `const ${alias} = require('${from}')`
+    }
+
+    /** @type {JavaScriptPrinter['printDeconstructedImport']} */
+    printDeconstructedImport (imports, from) {
+        return `const { ${imports.join(', ')} } = require('${from}')`
+    }
+
+    /** @type {JavaScriptPrinter['printExport']} */
+    printExport (name, value) {
+        return `module.exports.${name} = ${value}`
+    }
+
+    /** @type {JavaScriptPrinter['printDefaultExport']} */
+    printDefaultExport (value) {
+        // not exactly "default", but you catch the drift...
+        return `module.exports = ${value}`
+    }
+
+    /** @type {JavaScriptPrinter['nameFile']} */
+    nameFile (file) {
+        return `${file}.js`
+    }
+}
+
+/** @typedef {JavaScriptPrinter} Printer */
+
+module.exports = {
+    CJSPrinter,
+    ESMPrinter
+}

package/lib/{components → printers}/wrappers.js

@@ -87,6 +87,13 @@ const createObjectOf = t => `{${t}}`
  */
 const createUnionOf = (...types) => types.join(' | ')
 
+/**
+ * Wraps types into a intersection type string
+ * @param {string[]} types - an array of types
+ * @returns {string}
+ */
+const createIntersectionOf = (...types) => types.join(' & ')
+
 /**
  * Wraps type into a promise
  * @param {string} t - the type to wrap.
@@ -136,6 +143,7 @@ module.exports = {
     createObjectOf,
     createPromiseOf,
     createUnionOf,
+    createIntersectionOf,
     createToOneAssociation,
     createToManyAssociation,
     createCompositionOfOne,

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, createKey } = require('../components/wrappers')
+const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne, createKey } = require('../printers/wrappers')
 const { StructuredInlineDeclarationResolver } = require('../components/inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('../components/enum')
 const { isReferenceType } = require('../components/reference')

package/lib/typedefs.d.ts

@@ -202,6 +202,7 @@ export module config {
          * `IEEE754Compatible = true` -> any cds.Decimal will become `number | string`
          */
         IEEE754Compatible: boolean
+        targetModuleType: 'cjs' | 'esm' | 'auto'
     }
 }
 

package/lib/util.js

@@ -1,8 +1,9 @@
 /** @typedef { import('./typedefs').util.Annotations} Annotations */
-/** @typedef { import('./typedefs').util.CommandLineFlags } CommandlineFlag */
-/** @typedef { import('./typedefs').util.ParsedFlag } ParsedFlags */
 /** @typedef { import('./typedefs').resolver.EntityCSN } EntityCSN */
 
+const fs = require('node:fs')
+const path = require('node:path')
+
 // inflection functions are stolen from github/cap/dev/blob/main/etc/inflect.js
 
 // MONKEY PATCH to support Node v14
@@ -108,7 +109,7 @@ const singular4 = (dn, stripped = false) => {
 const plural4 = (dn, stripped) => {
     let n = dn.name ?? dn
     if (stripped) {
-        n = n.match(last)?.[0]
+        n = /** @type {string} */(n.match(last)?.[0])
     }
     return (
         getPluralAnnotation(dn) ??
@@ -125,8 +126,8 @@ const plural4 = (dn, stripped) => {
 /**
  * Performs a deep merge of the passed objects into the first object.
  * See Object.assign(target, source).
- * @param {object} target - object to assign into.
- * @param {object} source - object to assign from.
+ * @param {{[key: string]: any}} target - object to assign into.
+ * @param {{[key: string]: any}} source - object to assign from.
  */
 const deepMerge = (target, source) => {
     Object.keys(target)
@@ -135,11 +136,40 @@ const deepMerge = (target, source) => {
     Object.assign(target, source)
 }
 
+/**
+ * Tries to determine the project's target type (ESM or CJS).
+ * @param {string} root - the root of the project
+ * @returns {'esm' | 'cjs' | undefined}
+ */
+const getProjectTargetType = root => {
+    const isFsRoot = (/** @type {string} **/ dir) => dir === path.dirname(dir)
+    let dir = root
+    let packageJson
+
+    do {
+        packageJson = fs.readdirSync(dir).find(f => f.endsWith('package.json'))
+        if (packageJson) {
+            packageJson = path.join(dir, packageJson)
+        }
+        dir = path.dirname(dir)
+    } while (!packageJson && !isFsRoot(dir))
+
+    if (packageJson) {
+        const json = JSON.parse(fs.readFileSync(packageJson, 'utf-8'))
+        return json.type === 'module'
+            ? 'esm'
+            : 'cjs'
+    }
+    // no package.json found -> inconclusive
+    return undefined
+}
+
 module.exports = {
     annotations,
     camelToSnake,
     getSingularAnnotation,
     getPluralAnnotation,
+    getProjectTargetType,
     unlocalize,
     singular4,
     plural4,

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, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf } = require('./components/wrappers')
+const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf, createIntersectionOf, createReturnTypeOf } = require('./printers/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
@@ -138,11 +138,11 @@ class Visitor {
     #printStaticActions(entity, buffer, ancestors, file) {
         // TODO: refactor away! All these printing functionalities need to go
         const actions = Object.entries(entity.actions ?? {})
-        const inherited = ancestors.length
-            ? ancestors.map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.actions`).join(' & ') + ' & '
-            : ''
+        const inherited = ancestors.map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.actions`)
+
+        const typeBuffer = buffer.createSubBuffer()
         if (actions.length) {
-            buffer.addIndentedBlock(`declare static readonly actions: ${inherited}{`,
+            typeBuffer.addIndentedBlock(createIntersectionOf(...inherited, '{'),
                 () => {
                     for (const [aname, action] of actions) {
                         const [opener, content, closer] = SourceFile.stringifyLambda({
@@ -153,28 +153,34 @@ class Visitor {
                                 : 'any',
                             kind: action.kind,
                             doc: docify(action.doc)})
-                        buffer.addIndentedBlock(opener, content, closer)
+                        typeBuffer.addIndentedBlock(opener, content, closer)
                     }
-                }, '}'
-            ) // end of actions
+                }, '}')
         } else {
-            buffer.add(createMember({
-                name: 'actions',
-                type: `${inherited}${empty}`,
-                isStatic: true,
-                isReadonly: true
-            }))
+            typeBuffer.add(createIntersectionOf(...inherited, empty))
         }
+        buffer.add(createMember({
+            name: 'actions',
+            type: typeBuffer.join().trimStart(),  // remove leading whitespace from indentation, as type is printed in line
+            isStatic: true,
+            isReadonly: true,
+            isDeclare: true,
+        }))
     }
 
     /**
      * @param {Buffer} buffer - the buffer to write the keys into
      * @param {string} clean - the clean name of the entity
+     * @param {import('./typedefs').resolver.EntityInfo[]} ancestors - ancestors infos to include in they type
+     * @param {SourceFile} file - the file the entity is being printed into
      */
-    #printStaticKeys(buffer, clean) {
+    #printStaticKeys(buffer, clean, ancestors, file) {
+        const ancestorKeys = ancestors
+            .filter(a => Object.entries(a.csn.keys ?? {}).length)
+            .map(a => `typeof ${asIdentifier({info: a, relative: file.path})}.keys`)
         buffer.add(createMember({
             name: 'keys',
-            type: createKeysOf(clean),
+            type: createIntersectionOf(createKeysOf(clean), ...ancestorKeys),
             isDeclare: true,
             isStatic: true,
             isReadonly: true,
@@ -312,15 +318,15 @@ class Visitor {
                 if ('kind' in entity) {
                     buffer.add(createMember({
                         name: 'kind',
-                        type: '"entity" | "type" | "aspect"',
+                        type: createUnionOf(...['entity', 'type', 'aspect'].map(stringIdent)),
                         isStatic: true,
                         isReadonly: true,
                         isDeclare: false,
-                        isOverride: ancestorInfos.some(ancestor => ancestor.csn.kind),
+                        isOverride: ancestorInfos.some(({csn}) => csn.kind),
                         initialiser: stringIdent(entity.kind)
                     }))
                 }
-                this.#printStaticKeys(buffer, clean)
+                this.#printStaticKeys(buffer, clean, ancestorInfos, file)
                 this.#printStaticElements(buffer, clean)
                 this.#printStaticActions(entity, buffer, ancestorInfos, file)
             }, '};') // end of generated class
@@ -657,4 +663,3 @@ class Visitor {
 module.exports = {
     Visitor
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.28.1",
+  "version": "0.29.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",
@@ -123,6 +123,16 @@
               "type": "boolean",
               "description": "If set to true, floating point properties are generated\nas IEEE754 compatible '(number | string)' instead of 'number'.",
               "default": false
+            },
+            "target_module_type": {
+              "type": "string",
+              "description": "Output format for generated .js files.\nSetting it to auto tries to derive the module type from\nthe package.json and falls back to CJS.",
+              "enum": [
+                "esm",
+                "cjs",
+                "auto"
+              ],
+              "default": "auto"
             }
           }
         }