@cap-js/cds-typer 0.20.2 → 0.21.1

package/CHANGELOG.md

@@ -4,7 +4,26 @@ 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.21.0 - TBD
+## Version 0.22.0 - TBD
+
+## Version 0.21.1 - 2024-06-03
+### Fixed
+- Added missing _cds-plugin.js_ to exported files to properly enable calling `cds build --for typescript`
+
+
+## Version 0.21.0 - 2024-05-31
+### Added
+- Added `IEEE754Compatible` flag which, when set to `true`, generates decimal fields as `(number | string)` instead of `number`. This flag will be removed in the long run
+- Added plugin to `cds build` TypeScript projects. Can be explicitly called using `cds build --for typescript`
+
+### Changed
+- Types representing CDS events are now only `declare`d to avoid having to make their properties optional
+- Singular forms in generated _index.js_ files now contain a `.is_singular` property as marker for distinguished handling of singular and plural in the runtime
+- Parameters passed to the CLI now take precedence over configuration contained in the `typer` section of `cds.env`
+
+### Fixed
+- Entities ending with an "s" are no longer incorrectly truncated within `extends`-clauses
+- Entity names prefixed with their own namespace (e.g. `Name.Name`, `Name.NameAttachments`) are not stripped of their name prefix
 
 ## Version 0.20.2 - 2024-04-29
 ### Fixed
@@ -17,7 +36,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 ## Version 0.20.0 - 2024-04-23
 ### Added
 - Types for actions and functions now expose a `.kind` property which holds the string `'function'` or `'action'` respectively
-- Added the CdsDate, CdsDateTime, CdsTime, CdsTimestamp types, which are each represented as a `string`.
+- Added the `CdsDate`, `CdsDateTime`, `CdsTime`, `CdsTimestamp` types, which are each represented as a `string`.
 - Plural types can now also contain an optional numeric `$count` property
 
 ### Changed

package/cds-plugin.js

@@ -0,0 +1,126 @@
+const { readdir, stat } = require('node:fs/promises')
+const { normalize } = require('node:path')
+const cds = require('@sap/cds')
+const util = require('util')
+const exec = util.promisify(require('child_process').exec)
+const typer = require('./lib/compile')
+
+const { fs, path } = cds.utils
+const DEBUG = cds.debug('cli|build')
+const BUILD_CONFIG = 'tsconfig.cdsbuild.json'
+
+/**
+ * Check if a tsconfig file exists.
+ */
+const tsConfigExists = () => fs.existsSync('tsconfig.json')
+
+/**
+ * Check if separate tsconfig file that is used for building the project.
+ * @returns {boolean}
+ */
+const buildConfigExists = () => fs.existsSync(BUILD_CONFIG)
+
+/**
+ * @param {string} dir The directory to remove.
+ */
+const rmDirIfExists = dir => {
+    try { fs.rmSync(dir, { recursive: true }) } catch { /* ignore */ }
+}
+
+/**
+ * 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>}
+ */
+const rmFiles = async (dir, exts) => fs.existsSync(dir) 
+    ? Promise.all(
+        (await readdir(dir))
+            .map(async file => {
+                const filePath = path.join(dir, file)
+                if ((await stat(filePath)).isDirectory()) {
+                    return rmFiles(filePath, exts)
+                } else if (exts.some(ext => file.endsWith(ext))) {
+                    fs.unlinkSync(filePath)
+                }
+            })
+    )
+    : undefined
+
+// requires @sap/cds-dk version >= 7.5.0
+cds.build?.register?.('typescript', class extends cds.build.Plugin {
+    static taskDefaults = { src: '.' }
+    static hasTask() { return tsConfigExists() }
+
+    // lower priority than the nodejs task
+    get priority() { return -1 }
+
+    get #appFolder () { return cds?.env?.folders?.app ?? 'app' }
+
+    get #modelDirectoryName () {
+        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]
+            const directory = alias.match(/(?:\.\/)?(.*)\/\*\/index\.ts/)[1]
+            return normalize(directory)  // could contain forward slashes in tsconfig.json
+        } catch {
+            DEBUG?.('tsconfig.json not found, not parsable, or inconclusive. Using default model directory name')
+        }
+        return '@cds-models'
+    }
+
+    init() {
+        this.task.dest = path.join(cds.root, cds.env.build.target, cds.env.folders.srv)
+    }
+
+    async #runCdsTyper () {
+        DEBUG?.('running cds-typer')
+        await typer.compileFromFile('*', { outputDirectory: this.#modelDirectoryName })
+    }
+
+    async #buildWithConfig () {
+    // possibly referencing their tsconfig.json via "extends", specifying the "compilerOptions.outDir" and
+    // manually adding irrelevant folders (read: gen/ and app/) to the "exclude" array.
+        DEBUG?.(`building with config ${BUILD_CONFIG}`)
+        return exec(`npx tsc --project ${BUILD_CONFIG}`)
+    }
+
+    async #buildWithoutConfig () {
+        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}`)
+        rmDirIfExists(path.join(this.task.dest, cds.env.build.target))
+        rmDirIfExists(path.join(this.task.dest, this.#appFolder))
+    }
+
+    async #copyCleanModel (buildDirCdsModels) {
+    // copy models again, to revert transpilation thereof.
+    // We only need the index.js files in un-transpiled form.
+        await this.copy(this.#modelDirectoryName).to(buildDirCdsModels)
+        await rmFiles(buildDirCdsModels, ['.ts'])
+    }
+
+    async build() {
+        await this.#runCdsTyper()
+        const buildDirCdsModels = path.join(this.task.dest, this.#modelDirectoryName)
+        // remove the js files generated by the nodejs buildtask,
+        // leaving only json, cds, and other static files
+        await rmFiles(this.task.dest, ['.js', '.ts'])
+
+        try {
+            await (buildConfigExists() 
+                ? this.#buildWithConfig() 
+                : this.#buildWithoutConfig()
+            )
+        } catch (error) {
+            throw error.stdout
+                ? new Error(error.stdout)
+                : error
+        }
+        this.#copyCleanModel(buildDirCdsModels)
+    }
+})

package/lib/cli.js

@@ -41,6 +41,11 @@ const flags = {
         desc: `If set to true, properties in entities are${EOL}always generated as optional (a?: T).`,
         allowed: ['true', 'false'],
         default: 'true'
+    },
+    IEEE754Compatible: {
+        desc: `If set to true, floating point properties are generated${EOL}as IEEE754 compatible '(number | string)' instead of 'number'.`,
+        allowed: ['true', 'false'],
+        default: 'false'
     }
 }
 
@@ -93,7 +98,8 @@ const main = async args => {
         logLevel: Levels[args.named.logLevel] ?? args.named.logLevel,
         jsConfigPath: args.named.jsConfigPath,
         inlineDeclarations: args.named.inlineDeclarations,
-        propertiesOptional: args.named.propertiesOptional === 'true'
+        propertiesOptional: args.named.propertiesOptional === 'true',
+        IEEE754Compatible: args.named.IEEE754Compatible === 'true'
     })
 }
 

package/lib/compile.js

@@ -45,7 +45,7 @@ const writeJsConfig = (path, logger) => {
  */
 const compileFromCSN = async (csn, parameters) => {
     const envSettings = cds.env?.typer ?? {}
-    parameters = { ...parameters, ...envSettings }
+    parameters = { ...envSettings, ...parameters }
     const logger = new Logger()
     logger.addFrom(parameters.logLevel)
     if (parameters.jsConfigPath) {

package/lib/components/resolver.js

@@ -39,48 +39,61 @@ const { baseDefinitions } = require('./basedefs')
  * }} TypeResolveInfo
 */
 
-/**
- * Builtin types defined by CDS.
- */
-const Builtins = {
-    UUID: 'string',
-    String: 'string',
-    Binary: 'string',
-    LargeString: 'string',
-    LargeBinary: 'Buffer | string | {value: import("stream").Readable, $mediaContentType: string, $mediaContentDispositionFilename?: string, $mediaContentDispositionType?: string}',
-    Vector: 'string',
-    Integer: 'number',
-    UInt8: 'number',
-    Int16: 'number',
-    Int32: 'number',
-    Int64: 'number',
-    Integer64: 'number',
-    Decimal: 'number',
-    DecimalFloat: 'number',
-    Float: 'number',
-    Double: 'number',
-    Boolean: 'boolean',
-    // note: the date-related types are strings on purpose, which reflects their runtime behaviour
-    Date: '__.CdsDate',  // yyyy-mm-dd
-    DateTime: '__.CdsDateTime', // yyyy-mm-dd + time + TZ (precision: seconds)
-    Time: '__.CdsTime',  // hh:mm:ss
-    Timestamp: '__.CdsTimestamp', // yyy-mm-dd + time + TZ (ms precision)
-    //
-    Composition: 'Array',
-    Association: 'Array'
-}
+class BuiltinResolver {
+    /**
+     * Builtin types defined by CDS.
+     */
+    #builtins = {
+        UUID: 'string',
+        String: 'string',
+        Binary: 'string',
+        LargeString: 'string',
+        LargeBinary: 'Buffer | string | {value: import("stream").Readable, $mediaContentType: string, $mediaContentDispositionFilename?: string, $mediaContentDispositionType?: string}',
+        Vector: 'string',
+        Integer: 'number',
+        UInt8: 'number',
+        Int16: 'number',
+        Int32: 'number',
+        Int64: 'number',
+        Integer64: 'number',
+        Decimal: 'number',
+        DecimalFloat: 'number',
+        Float: 'number',
+        Double: 'number',
+        Boolean: 'boolean',
+        // note: the date-related types are strings on purpose, which reflects their runtime behaviour
+        Date: '__.CdsDate',  // yyyy-mm-dd
+        DateTime: '__.CdsDateTime', // yyyy-mm-dd + time + TZ (precision: seconds)
+        Time: '__.CdsTime',  // hh:mm:ss
+        Timestamp: '__.CdsTimestamp', // yyy-mm-dd + time + TZ (ms precision)
+        //
+        Composition: 'Array',
+        Association: 'Array'
+    }
 
-/**
- * @param {string | string[]} type name or parts of the type name split on dots
- * @returns {string | undefined | false} if t refers to a builtin, the name of the corresponding TS type is returned.
- *   If t _looks like_ a builtin (`cds.X`), undefined is returned.
- *   If t is obviously not a builtin, false is returned.
- */
-function resolveBuiltin (t) {
-    const path = Array.isArray(t) ? t : t.split('.')
-    return path.length === 2 && path[0] === 'cds'
-        ? Builtins[path[1]]
-        : false
+    constructor ({ IEEE754Compatible } = {}) {
+        if (IEEE754Compatible) {
+            this.#builtins.Decimal = '(number | string)'
+            this.#builtins.DecimalFloat = '(number | string)'
+            this.#builtins.Float = '(number | string)'
+            this.#builtins.Double = '(number | string)'
+        }
+        this.#builtins = Object.freeze(this.#builtins)
+    }
+
+    /**
+     * @param {string | string[]} type name or parts of the type name split on dots
+     * @returns {string | undefined | false} if t refers to a builtin, the name of the corresponding TS type is returned.
+     *   If t _looks like_ a builtin (`cds.X`), undefined is returned.
+     *   If t is obviously not a builtin, false is returned.
+     */
+    resolveBuiltin (t) {
+        if (!Array.isArray(t) && typeof t !== 'string') return false
+        const path = Array.isArray(t) ? t : t.split('.')
+        return path.length === 2 && path[0] === 'cds'
+            ? this.#builtins[path[1]]
+            : false
+    }
 }
 
 class Resolver {
@@ -135,6 +148,9 @@ class Resolver {
         /** @type {Visitor} */
         this.visitor = visitor
 
+        /** @type {BuiltinResolver} */
+        this.builtinResolver = new BuiltinResolver(visitor.options)
+
         /** @type {Library[]} */
         this.libraries = [new Library(require.resolve('../../library/cds.hana.ts'))]
 
@@ -171,7 +187,7 @@ class Resolver {
      * @returns {Untangled} untangled qualifier
      */
     untangle(fq) {
-        const builtin = resolveBuiltin(fq)
+        const builtin = this.builtinResolver.resolveBuiltin(fq)
         if (builtin) return { namespace: new Path([]), name: builtin, property: [], scope: [] }
 
         const ns = this.resolveNamespace(fq)
@@ -318,7 +334,7 @@ class Resolver {
             // don't slice off namespace if it isn't part of the inflected name.
             // This happens when the user adds an annotation and singular4 therefore
             // already returns an identifier without namespace. Plural has ns already sliced off.
-            if (namespace && singular.startsWith(namespace)) {
+            if (namespace && singular.startsWith(namespace+'.')) {
                 singular = singular.slice(namespace.length + 1)
             }
 
@@ -641,7 +657,7 @@ class Resolver {
     #resolveTypeName(t, into) {
         const result = into || {}
         const path = t.split('.')
-        const builtin = resolveBuiltin(path)
+        const builtin = this.builtinResolver.resolveBuiltin(path)
         if (builtin === undefined) {
             // looks like builtin, but isn't
             throw new Error(`Can not resolve apparent builtin type '${t}' to any CDS type.`)
@@ -698,6 +714,5 @@ class Resolver {
 }
 
 module.exports = {
-    Resolver,
-    resolveBuiltin
+    Resolver
 }

package/lib/file.js

@@ -391,18 +391,20 @@ class SourceFile extends File {
             // 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)
-            // by using a temporary Set we make sure to catch cases where
-            // (1) plural is the same as original (default case) and
-            // (2) plural differs from original, i.e. when a @plural annotation is present
-            //     or when plural4 produced weird inflection.
-                .flatMap(([singular, plural, original]) => Array.from(new Set([
-                    `module.exports.${singular} = csn.${original}`,
-                    /Array<.*>/.test(plural) ? undefined : `module.exports.${plural} = csn.${original}`,
+                .flatMap(([singular, plural, original]) => {
+                    const exports = [`module.exports.${singular} = { is_singular: true, __proto__: csn.${original} }`]
+                    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}`)
+                    }
                     // 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.
-                    `module.exports.${original} = csn.${original}`
-                ].filter(Boolean))))  // 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
+                    if (singular !== original) {
+                        exports.push(`module.exports.${original} = { is_singular: true, __proto__: csn.${original} }`)
+                    }
+                    return exports
+                })
             ) // singular -> plural aliases
             .concat(['// events'])
             .concat(this.events.fqs.map(({fq, name}) => `module.exports.${name} = '${fq}'`))

package/lib/visitor.js

@@ -6,7 +6,7 @@ const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, is
 // eslint-disable-next-line no-unused-vars
 const { SourceFile, FileRepository, Buffer } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
-const { Resolver, resolveBuiltin } = require('./components/resolver')
+const { Resolver } = require('./components/resolver')
 const { Logger } = require('./logging')
 const { docify } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
@@ -19,7 +19,7 @@ const { baseDefinitions } = require('./components/basedefs')
 
 /** 
  * @typedef { {
- *    rootDirectory: string, 
+ *    outputDirectory: string, 
  *    logLevel: number, 
  *    jsConfigPath?: string
  * }} CompileParameters
@@ -227,13 +227,16 @@ class Visitor {
                 file.addImport(namespace)
                 return [namespace, name, parent]
             })
-            .concat([[undefined, clean, [namespace, clean].filter(Boolean).join('.')]]) // add own aspect without namespace AFTER imports were created
+            .concat([[undefined, clean, name]]) // add own aspect without namespace AFTER imports were created
+            //.concat([[undefined, clean, [namespace, clean].filter(Boolean).join('.')]]) // add own aspect without namespace AFTER imports were created
             .reverse() // reverse so that own aspect A is applied before extensions B,C: B(C(A(Entity)))
             .reduce((wrapped, [ns, n, fq]) => {
                 // types are not inflected, so don't change those to singular
                 const refersToType = isType(this.csn.inferred.definitions[fq])
-                const ident = identAspect(refersToType ? n : util.singular4(n))
-
+                const ident = identAspect(refersToType 
+                    ? n 
+                    : this.resolver.inflect({csn: this.csn.inferred.definitions[fq], plainName: n}).singular
+                )
                 return !ns || ns.isCwd(file.path.asDirectory())
                     ? `${ident}(${wrapped})`
                     : `${ns.asIdentifier()}.${ident}(${wrapped})` 
@@ -307,6 +310,7 @@ class Visitor {
         this.#aspectify(name, target, buffer, { cleanName: singular })
 
         buffer.add(overrideNameProperty(singular, entity.name))
+        buffer.add(`Object.defineProperty(${singular}, 'is_singular', { value: true })`)
 
         // PLURAL
 
@@ -349,7 +353,7 @@ class Visitor {
     #stringifyFunctionParamType(type, file) {
         // if type.type is not 'cds.String', 'cds.Integer', ..., then we are actually looking
         // at a named enum type. In that case also resolve that type name
-        if (type.enum && resolveBuiltin(type.type)) return stringifyEnumType(csnToEnumPairs(type))
+        if (type.enum && this.resolver.builtinResolver.resolveBuiltin(type.type)) return stringifyEnumType(csnToEnumPairs(type))
         const paramType = this.resolver.resolveAndRequire(type, file)
         return this.inlineDeclarationResolver.getPropertyDatatype(
             paramType,
@@ -384,7 +388,7 @@ class Visitor {
         // 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 ('enum' in type && !isReferenceType(type) && resolveBuiltin(type.type)) {
+        if ('enum' in type && !isReferenceType(type) && this.resolver.builtinResolver.resolveBuiltin(type.type)) {
             file.addEnum(name, clean, csnToEnumPairs(type))
         } else {
             // alias
@@ -412,7 +416,8 @@ class Visitor {
         file.addEvent(clean, name)
         const buffer = file.events.buffer
         buffer.add('// event')
-        buffer.addIndentedBlock(`export class ${clean} {`, function() {
+        // only declare classes, as their properties are not optional, so we don't have to do awkward initialisation thereof.
+        buffer.addIndentedBlock(`export declare class ${clean} {`, function() {
             const propOpt = this.options.propertiesOptional
             this.options.propertiesOptional = false
             for (const [ename, element] of Object.entries(event.elements ?? {})) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.20.2",
+  "version": "0.21.1",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
   "repository": "github:cap-js/cds-typer",
@@ -31,7 +31,8 @@
     "CHANGELOG.md",
     "index.js",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "cds-plugin.js"
   ],
   "types": "index.d.ts",
   "bin": {