@cap-js/cds-typer 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -4,7 +4,11 @@ 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.17.0 - TBD
+## Version 0.18.0 - TBD
+
+## Version 0.17.0 - 2024-03-05
+### Fixed
+- Fixed a bug where refering to an externally defined enum via the `typeof` syntax would crash the type generation
 
 ## Version 0.16.0 - 2024-02-01
 ### Changed

package/lib/components/enum.js

@@ -29,13 +29,9 @@ const { normalise } = require('./identifier')
 function printEnum(buffer, name, kvs, options = {}) {
     const opts = {...{export: true}, ...options} 
     buffer.add('// enum')
-    buffer.add(`${opts.export ? 'export ' : ''}const ${name} = {`)
-    buffer.indent()
-    for (const [k, v] of kvs) {
-        buffer.add(`${normalise(k)}: ${v},`)
-    }
-    buffer.outdent()
-    buffer.add('} as const;')
+    buffer.addIndentedBlock(`${opts.export ? 'export ' : ''}const ${name} = {`, () =>
+        kvs.forEach(([k, v]) => buffer.add(`${normalise(k)}: ${v},`))
+    , '} as const;')
     buffer.add(`${opts.export ? 'export ' : ''}type ${name} = ${stringifyEnumType(kvs)}`)
     buffer.add('')
 }

package/lib/components/reference.js

@@ -0,0 +1,23 @@
+/**
+ * Check if an element references another type.
+ * This happens for foreign key relationships
+ * and for the typeof syntax.
+ * 
+ * ```cds
+ * entity E {
+ *   x: Integer
+ * }
+ * 
+ * entity F {
+ *   y: E.x  // <- ref
+ * }
+ * ```
+ * 
+ * @param {{type: any}} element
+ * @returns boolean
+ */
+const isReferenceType = (element) => element.type && Object.hasOwn(element.type, 'ref')
+
+module.exports = {
+    isReferenceType
+}

package/lib/components/resolver.js

@@ -6,6 +6,7 @@ const { Buffer, SourceFile, Path, Library, baseDefinitions } = require('../file'
 const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne } = require('./wrappers')
 const { StructuredInlineDeclarationResolver } = require('./inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('./enum')
+const { isReferenceType } = require('./reference')
 
 /** @typedef {{ cardinality?: { max?: '*' | number } }} EntityCSN */
 /** @typedef {{ definitions?: Object<string, EntityCSN> }} CSN */
@@ -55,7 +56,7 @@ const Builtins = {
     Float: 'number',
     Double: 'number',
     Boolean: 'boolean',
-    // note: the date-related types _can_ be Date in some cases, but let's start with string
+    // note: the date-related types are strings on purpose, which reflects their runtime behaviour
     Date: 'string',  // yyyy-mm-dd
     DateTime: 'string', // yyyy-mm-dd + time + TZ (precision: seconds
     Time: 'string',
@@ -370,7 +371,7 @@ class Resolver {
             result.type = '{}'
             result.isInlineDeclaration = true
         } else {
-            if (isInlineEnumType(element, this.csn)) {
+            if (!isReferenceType(element) && isInlineEnumType(element, this.csn)) {
                 // element.parent is only set if the enum is attached to an entity's property.
                 // If it is missing then we are dealing with an inline parameter type of an action.
                 // Edge case: element.parent is set, but no .name property is attached. This happens

package/lib/csn.js

@@ -234,10 +234,12 @@ function amendCSN(csn) {
  */
 const isView = entity => entity.query && !entity.projection
 
+const isDraftEnabled = entity => entity['@odata.draft.enabled'] === true
+
 /**
  * @see isView
  * Unresolved entities have to be looked up from inferred csn.
  */
 const isUnresolved = entity => entity._unresolved === true
 
-module.exports = { amendCSN, isView, isUnresolved, propagateForeignKeys }
+module.exports = { amendCSN, isView, isDraftEnabled, isUnresolved, propagateForeignKeys }

package/lib/file.js

@@ -93,10 +93,13 @@ class Library extends File {
  * Source file containing several buffers.
  */
 class SourceFile extends File {
+    /**
+     * @param {string | Path} path 
+     */
     constructor(path) {
         super()
         /** @type {Path} */
-        this.path = new Path(path.split('.'))
+        this.path = path instanceof Path ? path : new Path(path.split('.'))
         /** @type {Object} */
         this.imports = {}
         /** @type {Buffer} */
@@ -480,6 +483,33 @@ class Buffer {
     add(part) {
         this.parts.push(this.currentIndent + part)
     }
+
+    /**
+     * Adds an element to the buffer with one level of indent.
+     * @param {string | (() => void)} part either a string or a function. If it is a string, it is added to the buffer. 
+     * If not, it is expected to be a function that manipulates the buffer as a side effect.
+     */
+    addIndented(part) {
+        this.indent()
+        if (typeof part === 'function') {
+            part()
+        } else if (Array.isArray(part)) {
+            part.forEach(p => this.add(p))
+        }
+        this.outdent()
+    }
+
+    /**
+     * Adds an element to a buffer with one level of indent and and opener and closer surrounding it.
+     * @param {string} opener the string to put before the indent
+     * @param {string} content the content to indent (see {@link addIndented})
+     * @param {string} closer the string to put after the indent
+     */
+    addIndentedBlock(opener, content, closer) {
+        this.add(opener)
+        this.addIndented(content)
+        this.add(closer)
+    }
 }
 
 /**
@@ -548,6 +578,38 @@ class Path {
     }
 }
 
+// TODO: having the repository pattern in place we can separate (some of) the printing logic from the visitor.
+// Most of it hinges primarily on resolving specific files. We can now pass the repository and the resolver to a printer.
+class FileRepository {
+    #files = {}
+
+    /**
+     * @param {string} name
+     * @param {SourceFile} file 
+     */
+    add(name, file) {
+        this.#files[name] = file
+    }
+
+    /**
+     * Determines the file corresponding to the namespace.
+     * If no such file exists yet, it is created first.
+     * @param {string | Path} path the name of the namespace (foo.bar.baz)
+     * @returns {SourceFile} the file corresponding to that namespace name
+     */
+    getNamespaceFile(path) {
+        const key = path instanceof Path ? path.asNamespace() : path
+        return (this.#files[key] ??= new SourceFile(path))
+    }
+
+    /**
+     * @returns {SourceFile[]}
+     */
+    getFiles() {
+        return Object.values(this.#files)
+    }
+}
+
 /**
  * Base definitions used throughout the typing process,
  * such as Associations and Compositions.
@@ -583,7 +645,7 @@ export type EntitySet<T> = T[] & {
 
 export type DeepRequired<T> = { 
     [K in keyof T]: DeepRequired<T[K]>
-} & Required<T>;
+} & Exclude<Required<T>, null>;
 `)
 
 /**
@@ -618,6 +680,7 @@ module.exports = {
     Library,
     Buffer,
     File,
+    FileRepository,
     SourceFile,
     Path,
     writeout,

package/lib/visitor.js

@@ -2,14 +2,15 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved, propagateForeignKeys } = require('./csn')
+const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled } = require('./csn')
 // eslint-disable-next-line no-unused-vars
-const { SourceFile, baseDefinitions, Buffer } = require('./file')
+const { SourceFile, FileRepository, baseDefinitions, Buffer } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./components/resolver')
 const { Logger } = require('./logging')
 const { docify } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
+const { isReferenceType } = require('./components/reference')
 
  /** @typedef {import('./file').File} File */
  /** @typedef {{ entity: String }} Context */
@@ -54,7 +55,7 @@ class Visitor {
      * @returns {File[]} a full list of files to be written
      */
     getWriteoutFiles() {
-        return Object.values(this.files).concat(this.resolver.getUsedLibraries())
+        return this.fileRepository.getFiles().concat(this.resolver.getUsedLibraries())
     }
 
     /**
@@ -74,9 +75,9 @@ class Visitor {
         /** @type {Resolver} */
         this.resolver = new Resolver(this)
 
-        /** @type {Object<string, File>} */
-        this.files = {}
-        this.files[baseDefinitions.path.asIdentifier()] = baseDefinitions
+        /** @type {FileRepository} */
+        this.fileRepository = new FileRepository()
+        this.fileRepository.add(baseDefinitions.path.asNamespace(), baseDefinitions)
         this.inlineDeclarationResolver =
             this.options.inlineDeclarations === 'structured'
                 ? new StructuredInlineDeclarationResolver(this)
@@ -85,16 +86,6 @@ class Visitor {
         this.visitDefinitions()
     }
 
-    /**
-     * Determines the file corresponding to the namespace.
-     * If no such file exists yet, it is created first.
-     * @param {string} path the name of the namespace (foo.bar.baz)
-     * @returns {SourceFile} the file corresponding to that namespace name
-     */
-    getNamespaceFile(path) {
-        return (this.files[path] ??= new SourceFile(path))
-    }
-
     /**
      * Visits all definitions within the CSN definitions.
      */
@@ -163,7 +154,7 @@ class Visitor {
     #aspectify(name, entity, buffer, cleanName = undefined) {
         const clean = cleanName ?? this.resolver.trimNamespace(name)
         const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const file = this.fileRepository.getNamespaceFile(ns)
 
         const identSingular = (name) => name
         const identAspect = (name) => `_${name}Aspect`
@@ -171,66 +162,54 @@ class Visitor {
         this.contexts.push({ entity: name })
 
         // CLASS ASPECT
-        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`)
-        buffer.indent()
-        buffer.add(`return class ${clean} extends Base {`)
-        buffer.indent()
-
-        const enums = []
-        const exclusions = new Set(entity.projection?.excluding ?? [])
-        const elements = Object.entries(entity.elements ?? {}).filter(([ename]) => !exclusions.has(ename))
-        for (const [ename, element] of elements) {
-            this.visitElement(ename, element, file, buffer)
-
-            // make foreign keys explicit
-            if ('target' in element) {
-                // lookup in cds.definitions can fail for inline structs.
-                // We don't really have to care for this case, as keys from such structs are _not_ propagated to
-                // the containing entity.
-                for (const [kname, kelement] of this.#keys(element.target)) {
-                    if (this.resolver.getMaxCardinality(element) === 1) {
-                        const foreignKey = `${ename}_${kname}`
-                        if (Object.hasOwn(entity.elements, foreignKey)) {
-                            this.logger.error(`Attempting to generate a foreign key reference called '${foreignKey}' in type definition for entity ${name}. But a property of that name is already defined explicitly. Consider renaming that property.`)
-                        } else {
-                            kelement.isRefNotNull = !!element.notNull || !!element.key
-                            this.visitElement(foreignKey, kelement, file, buffer)
+        buffer.addIndentedBlock(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => object>(Base: TBase) {`, function () {
+            buffer.addIndentedBlock(`return class ${clean} extends Base {`, function () {
+                const enums = []
+                const exclusions = new Set(entity.projection?.excluding ?? [])
+                const elements = Object.entries(entity.elements ?? {}).filter(([ename]) => !exclusions.has(ename))
+                for (const [ename, element] of elements) {
+                    this.visitElement(ename, element, file, buffer)
+
+                    // make foreign keys explicit
+                    if ('target' in element) {
+                        // lookup in cds.definitions can fail for inline structs.
+                        // We don't really have to care for this case, as keys from such structs are _not_ propagated to
+                        // the containing entity.
+                        for (const [kname, kelement] of this.#keys(element.target)) {
+                            if (this.resolver.getMaxCardinality(element) === 1) {  // FIXME: kelement?
+                                const foreignKey = `${ename}_${kname}`
+                                if (Object.hasOwn(entity.elements, foreignKey)) {
+                                    this.logger.error(`Attempting to generate a foreign key reference called '${foreignKey}' in type definition for entity ${name}. But a property of that name is already defined explicitly. Consider renaming that property.`)
+                                } else {
+                                    kelement.isRefNotNull = !!element.notNull || !!element.key
+                                    this.visitElement(foreignKey, kelement, file, buffer)
+                                }
+                            }
                         }
                     }
-                }
-            }
 
-            // store inline enums for later handling, as they have to go into one common "static elements" wrapper
-            if (isInlineEnumType(element, this.csn.xtended)) {
-                enums.push(element)
-            }
-        }
-
-        buffer.indent()
-        for (const e of enums) {
-            buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
-            file.addInlineEnum(clean, name, e.name, csnToEnumPairs(e, {unwrapVals: true}))
-        }
-        buffer.add('static actions: {')
-        buffer.indent()
-        for (const [aname, action] of Object.entries(entity.actions ?? {})) {
-            buffer.add(
-                SourceFile.stringifyLambda({
-                    name: aname,
-                    parameters: this.#stringifyFunctionParams(action.params, file),
-                    returns: action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any'
-                    //initialiser: `undefined as unknown as typeof ${clean}.${aname}`,
-                })
-            )
-        }
-        buffer.outdent()
-        buffer.outdent()
-        buffer.add('}') // end of actions
+                    // store inline enums for later handling, as they have to go into one common "static elements" wrapper
+                    if (isInlineEnumType(element, this.csn.xtended)) {
+                        enums.push(element)
+                    }
+                }
 
-        buffer.outdent()
-        buffer.add('};') // end of generated class
-        buffer.outdent()
-        buffer.add('}')  // end of aspect
+                buffer.addIndented(function() {
+                    for (const e of enums) {
+                        buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
+                        file.addInlineEnum(clean, name, e.name, csnToEnumPairs(e, {unwrapVals: true}))
+                    }
+                    const actions = Object.entries(entity.actions ?? {})
+                    buffer.addIndentedBlock('static actions: {', 
+                        actions.map(([aname, action]) => SourceFile.stringifyLambda({
+                            name: aname,
+                            parameters: this.#stringifyFunctionParams(action.params, file),
+                            returns: action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any'
+                        }))
+                    , '}') // end of actions
+                }.bind(this))
+            }.bind(this), '};') // end of generated class
+        }.bind(this), '}') // end of aspect
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
@@ -255,12 +234,8 @@ class Visitor {
         this.contexts.pop()
     }
 
-    #isDraftEnabled(entity) {
-        return entity['@odata.draft.enabled'] === true
-    }
-
     #staticClassContents(clean, entity) {
-        return this.#isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : []
+        return isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : []
     }
 
     #printEntity(name, entity) {
@@ -268,7 +243,7 @@ class Visitor {
         const overrideNameProperty = (clazz, content) => `Object.defineProperty(${clazz}, 'name', { value: '${content}' })`
         const clean = this.resolver.trimNamespace(name)
         const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const file = this.fileRepository.getNamespaceFile(ns)
         // entities are expected to be in plural anyway, so we would favour the regular name.
         // If the user decides to pass a @plural annotation, that gets precedence over the regular name.
         let plural = this.resolver.trimNamespace(util.getPluralAnnotation(entity) ? util.plural4(entity, false) : name)
@@ -354,7 +329,7 @@ class Visitor {
         // FIXME: mostly duplicate of printAction -> reuse
         this.logger.debug(`Printing function ${name}:\n${JSON.stringify(func, null, 2)}`)
         const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const file = this.fileRepository.getNamespaceFile(ns)
         const params = this.#stringifyFunctionParams(func.params, file)
         const returns = this.resolver.visitor.inlineDeclarationResolver.getPropertyDatatype(
             this.resolver.resolveAndRequire(func.returns, file)
@@ -365,7 +340,7 @@ class Visitor {
     #printAction(name, action) {
         this.logger.debug(`Printing action ${name}:\n${JSON.stringify(action, null, 2)}`)
         const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const file = this.fileRepository.getNamespaceFile(ns)
         const params = this.#stringifyFunctionParams(action.params, file)
         const returns = this.resolver.visitor.inlineDeclarationResolver.getPropertyDatatype(
             this.resolver.resolveAndRequire(action.returns, file)
@@ -375,10 +350,9 @@ class Visitor {
 
     #printType(name, type) {
         this.logger.debug(`Printing type ${name}:\n${JSON.stringify(type, null, 2)}`)
-        const clean = this.resolver.trimNamespace(name)
-        const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
-        if ('enum' in type) {
+        const [ns, clean] = this.resolver.untangle(name)
+        const file = this.fileRepository.getNamespaceFile(ns)
+        if ('enum' in type && !isReferenceType(type)) {  // skip references to enums
             file.addEnum(name, clean, csnToEnumPairs(type))
         } else {
             // alias
@@ -389,9 +363,8 @@ class Visitor {
 
     #printAspect(name, aspect) {
         this.logger.debug(`Printing aspect ${name}`)
-        const clean = this.resolver.trimNamespace(name)
-        const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const [ns, clean] = this.resolver.untangle(name)
+        const file = this.fileRepository.getNamespaceFile(ns)
         // 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.
         // So we separate them into another buffer which is printed before the classes.
@@ -402,28 +375,25 @@ class Visitor {
 
     #printEvent(name, event) {
         this.logger.debug(`Printing event ${name}`)
-        const clean = this.resolver.trimNamespace(name)
-        const ns = this.resolver.resolveNamespace(name.split('.'))
-        const file = this.getNamespaceFile(ns)
+        const [ns, clean] = this.resolver.untangle(name)
+        const file = this.fileRepository.getNamespaceFile(ns)
         file.addEvent(clean, name)
         const buffer = file.events.buffer
         buffer.add('// event')
-        buffer.add(`export class ${clean} {`)
-        buffer.indent()
-        const propOpt = this.options.propertiesOptional
-        this.options.propertiesOptional = false
-        for (const [ename, element] of Object.entries(event.elements ?? {})) {
-            this.visitElement(ename, element, file, buffer)
-        }
-        this.options.propertiesOptional = propOpt
-        buffer.outdent()
-        buffer.add('}')
+        buffer.addIndentedBlock(`export class ${clean} {`, function() {
+            const propOpt = this.options.propertiesOptional
+            this.options.propertiesOptional = false
+            for (const [ename, element] of Object.entries(event.elements ?? {})) {
+                this.visitElement(ename, element, file, buffer)
+            }
+            this.options.propertiesOptional = propOpt
+        }.bind(this), '}')
     }
 
     #printService(name, service) {
         this.logger.debug(`Printing service ${name}:\n${JSON.stringify(service, null, 2)}`)
         const ns = this.resolver.resolveNamespace(name)
-        const file = this.getNamespaceFile(ns)
+        const file = this.fileRepository.getNamespaceFile(ns)
         // service.name is clean of namespace
         file.services.buffer.add(`export default { name: '${service.name}' }`)
         file.addService(service.name)

package/package.json

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