@cap-js/cds-typer 0.2.5-beta.1 → 0.4.0

package/lib/file.js

@@ -101,11 +101,11 @@ class SourceFile extends File {
         this.preamble = new Buffer()
         /** @type {Buffer} */
         this.types = new Buffer()
-        /** @type {Buffer} */
-        this.enums = new Buffer()
+        /** @type {{ buffer: Buffer, fqs: {name: string, fq: string}[]}} */
+        this.enums = { buffer: new Buffer(), fqs: [] }
         /** @type {Buffer} */
         this.classes = new Buffer()
-        /** @type {{ buffer: Buffer, names: string[]} */
+        /** @type {{ buffer: Buffer, names: string[]}} */
         this.actions = { buffer: new Buffer(), names: [] }
         /** @type {Buffer} */
         this.aspects = new Buffer()
@@ -136,6 +136,19 @@ class SourceFile extends File {
         this.inflections.push([singular, plural, original])
     }
 
+    /**
+     * Adds a function definition in form of a arrow function to the file.
+     * @param {string} name name of the function
+     * @param {{relative: string | undefined, local: boolean, posix: boolean}} params list of parameters, passed as [name, type] pairs
+     * @param returns the return type of the function
+     */
+    addFunction(name, params, returns) {
+        // FIXME: use different buffers for buffers and actions, or at least rename buffer to the more general category "functions"?
+        this.actions.buffer.add("// function")
+        this.actions.buffer.add(`export declare const ${SourceFile.stringifyLambda(name, params, returns)};`)
+        this.actions.names.push(name)
+    }
+
     /**
      * Adds an action definition in form of a arrow function to the file.
      * @param {string} name name of the action
@@ -178,13 +191,26 @@ class SourceFile extends File {
      * @param {[string, string][]} kvs list of key-value pairs
      */
     addEnum(fq, name, kvs) {
-        this.enums.add(`export enum ${name} {`)
-        this.enums.indent()
+        // CDS differ from TS enums as they can use bools as value (TS: only number and string)
+        // So we have to emulate enums by adding an object (name -> value mappings)
+        // and a type containing all disctinct values.
+        // We can get away with this as TS doesn't feature nominal typing, so the structure
+        // is all we care about.
+        this.enums.fqs.push({ name, fq })
+        const bu = this.enums.buffer
+        bu.add('// enum')
+        bu.add(`export const ${name} = {`)
+        bu.indent()
+        const vals = new Set()
         for (const [k, v] of kvs) {
-            this.enums.add(`${k} = ${v},`)
+            bu.add(`${k}: ${v},`)
+            vals.add(v)
         }
-        this.enums.outdent()
-        this.enums.add('}')
+        bu.outdent()
+        bu.add('}')
+        bu.add(`export type ${name} = ${[...vals].join(' | ')}`)
+        bu.add('')
+        
     }
 
     /**
@@ -259,7 +285,7 @@ class SourceFile extends File {
             this.getImports().join(),
             this.preamble.join(),
             this.types.join(),
-            this.enums.join(),
+            this.enums.buffer.join(),
             namespaces.join(),
             this.aspects.join(), // needs to be before classes
             this.classes.join(),
@@ -287,6 +313,8 @@ class SourceFile extends File {
             ) // singular -> plural aliases
             .concat(['// actions'])
             .concat(this.actions.names.map(name => `module.exports.${name} = '${name}'`))
+            .concat(['// enums'])
+            .concat(this.enums.fqs.map(({fq, name}) => `module.exports.${name} = Object.fromEntries(Object.entries(cds.model.definitions['${fq}'].enum).map(([k,v]) => [k,v.val]))`))
             .join('\n') + '\n'
     }
 }
@@ -428,6 +456,7 @@ class Path {
  * @type {SourceFile}
  */
 const baseDefinitions = new SourceFile('_')
+// FIXME: this should be a library someday
 baseDefinitions.addPreamble(`
 export namespace Association {
     export type to <T> = T;

package/lib/logging.js

@@ -16,15 +16,16 @@ class Logger {
         for (let i = 0; i < lvls.length - 1; i++) {
             // -1 to ignore NONE
             const level = lvls[i]
-            this[level.toLowerCase()] = function (message) {
-                this._log(level, message)
-            }.bind(this)
+            this[level.toLowerCase()] = function (message) { this._log(level, message) }.bind(this)
         }
     }
 
+    // only temporarily to disable those warnings...
+    //warning(s) {}; error(s) {}; info(s) {}; debug(s) {};
+
     /**
      * Add all log levels starting at level.
-     * @param {number} level level to start from.
+     * @param {number} baseLevel level to start from.
      */
     addFrom(baseLevel) {
         const vals = Object.values(Levels)

package/lib/util.js

@@ -61,9 +61,9 @@ const unlocalize = (name) => {
  * Attempts to derive the singular form of an English noun.
  * If '@singular' is passed as annotation, that is preferred.
  * @param {Annotations} dn annotations
- * @param {boolean} stripped if true, leading namespace will be stripped
+ * @param {boolean?} stripped if true, leading namespace will be stripped
  */
-const singular4 = (dn, stripped) => {
+const singular4 = (dn, stripped = false) => {
     let n = dn.name || dn
     if (stripped) {
         n = n.match(last)[0]
@@ -184,6 +184,48 @@ const parseCommandlineArgs = (argv, validFlags) => {
     }
 }
 
+/** 
+* Entities inherit their ancestors annotations:
+* https://cap.cloud.sap/docs/cds/cdl#annotation-propagation
+* This is a problem if we annotate @singular/ @plural to an entity A,
+* as we don't want all descendents B, C, ... to share the ancestor's
+* annotated inflexion
+* -> remove all such annotations that appear in a parent as well.
+* BUT: we can't just delete the attributes. Imagine three classes
+* A <- B <- C
+* where A contains a @singular annotation.
+* If we erase the annotation from B, C will still contain it and
+* can not detect that its own annotation was inherited without
+* travelling up the entire inheritance chain up to A.
+* So instead, we monkey patch and maintain a dictionary "erased"
+* when removing an annotation which we also check.
+*/
+function fixCSN(csn) {
+    const erase = (entity, parent, attr) => {
+        if (attr in entity) {
+            const ea = entity[attr]
+            if (parent[attr] === ea || (parent.erased && parent.erased[attr] === ea)) {
+                entity.erased ??= {}
+                entity.erased[attr] = ea
+                delete entity[attr]
+                //this.logger.info(`Removing inherited attribute ${attr} from ${entity.name}.`)
+            }
+        }
+    }
+
+    for (const entity of Object.values(csn.definitions)) {
+        let i = 0
+        while (
+            (getSingularAnnotation(entity) || getPluralAnnotation(entity)) &&
+            i < (entity.includes ?? []).length
+        ) {
+            const parent = csn.definitions[entity.includes[i]]
+            Object.values(annotations).flat().forEach(an => erase(entity, parent, an))
+            i++
+        }
+    }
+}
+
 module.exports = {
     annotations,
     getSingularAnnotation,
@@ -193,4 +235,5 @@ module.exports = {
     plural4,
     parseCommandlineArgs,
     deepMerge,
+    fixCSN
 }

package/lib/visitor.js

@@ -0,0 +1,353 @@
+'use strict'
+
+const util = require('./util')
+
+const { SourceFile, baseDefinitions, Buffer } = require('./file')
+const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
+const { Resolver } = require('./components/resolver')
+const { Logger } = require('./logging')
+const { docify } = require('./components/wrappers')
+
+ /** @typedef {import('./file').File} File */
+ /** @typedef {{ entity: String }} Context */
+
+ /** 
+ * @typedef { {
+ *    rootDirectory: string, 
+ *    logLevel: number, 
+ *    jsConfigPath?: string
+ * }} CompileParameters
+ */
+
+ /** 
+ * - `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable)
+ * - `inlineDeclarations = 'structured'` -> @see inline.StructuredInlineDeclarationResolver
+ * - `inlineDeclarations = 'flat'` -> @see inline.FlatInlineDeclarationResolver
+ * @typedef { { 
+  *    propertiesOptional: boolean,
+  *    inlineDeclarations: 'flat' | 'structured',
+ * }} VisitorOptions 
+ */
+
+ /**
+  * @typedef {{
+  *   typeName: string,
+  *   singular: string,
+  *   plural: string
+  * }} Inflection
+  */
+
+const defaults = {
+    // FIXME: add defaults for remaining parameters
+    propertiesOptional: true,
+    inlineDeclarations: 'flat'
+}
+
+class Visitor {
+    /**
+     * Gathers all files that are supposed to be written to
+     * the type directory. Including generated source files,
+     * as well as library files.
+     * @returns {File[]} a full list of files to be written
+     */
+    getWriteoutFiles() {
+        return Object.values(this.files).concat(this.resolver.getUsedLibraries())
+    }
+
+    /**
+     * @param csn root CSN
+     * @param {VisitorOptions} options
+     */
+    constructor(csn, options = {}, logger = new Logger()) {
+        util.fixCSN(csn)
+        this.options = { ...defaults, ...options }
+        this.logger = logger
+        this.csn = csn
+
+        /** @type {Context[]} **/
+        this.contexts = []
+
+        /** @type {Resolver} */
+        this.resolver = new Resolver(this)
+
+        /** @type {Object<string, File>} */
+        this.files = {}
+        this.files[baseDefinitions.path.asIdentifier()] = baseDefinitions
+        this.inlineDeclarationResolver =
+            this.options.inlineDeclarations === 'structured'
+                ? new StructuredInlineDeclarationResolver(this)
+                : new FlatInlineDeclarationResolver(this)
+
+        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.
+     */
+    visitDefinitions() {
+        for (const [name, entity] of Object.entries(this.csn.definitions)) {
+            this.visitEntity(name, entity)
+        }
+    }
+
+    /**
+     * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
+     * That is, for an element A we get:
+     * - the function A(B) to mix the aspect into another class B
+     * - the const AXtended which represents the entity A with all of its aspects mixed in (this const is not exported)
+     * - the type A to use for external typing and is derived from AXtended.
+     * @param {string} name the name of the entity
+     * @param {CSN} element the pointer into the CSN to extract the elements from
+     * @param {Buffer} buffer the buffer to write the resulting definitions into
+     * @param {string?} cleanName the clean name to use. If not passed, it is derived from the passed name instead.
+     */
+    _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 identSingular = (name) => name
+        const identAspect = (name) => `_${name}Aspect`
+
+        this.contexts.push({
+            entity: name,
+        })
+
+        // CLASS ASPECT
+        buffer.add(`export function ${identAspect(clean)}<TBase extends new (...args: any[]) => any>(Base: TBase) {`)
+        buffer.indent()
+        buffer.add(`return class ${clean} extends Base {`)
+        buffer.indent()
+        for (const [ename, element] of Object.entries(entity.elements ?? {})) {
+            this.visitElement(ename, element, file, buffer)
+        }
+        for (const [aname, action] of Object.entries(entity.actions ?? {})) {
+            buffer.add(
+                SourceFile.stringifyLambda(
+                    aname,
+                    Object.entries(action.params ?? {}).map(([n, t]) => [
+                        n,
+                        this.resolver.resolveAndRequire(t, file).typeName,
+                    ]),
+                    action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any'
+                )
+            )
+            //this.visitEntity(aname, action, file, buffer)
+        }
+        buffer.outdent()
+        buffer.add('};')
+        buffer.outdent()
+        buffer.add('}')
+
+        // CLASS WITH ADDED ASPECTS
+        file.addImport(baseDefinitions.path)
+        const rhs = (entity.includes ?? [])
+            .map((parent) => {
+                const [ns, n] = this.resolver.untangle(parent)
+                file.addImport(ns)
+                return [ns, n]
+            })
+            .concat([[undefined, clean]]) // 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]) =>
+                    !ns || ns.isCwd(file.path.asDirectory())
+                        ? `${identAspect(n)}(${wrapped})`
+                        : `${ns.asIdentifier()}.${identAspect(n)}(${wrapped})`,
+                `${baseDefinitions.path.asIdentifier()}.Entity`
+            )
+
+        buffer.add(`export class ${identSingular(clean)} extends ${rhs} {}`)
+        //buffer.add(`export type ${clean} = InstanceType<typeof ${identSingular(clean)}>`)
+        this.contexts.pop()
+    }
+
+    #printEntity(name, entity) {
+        const clean = this.resolver.trimNamespace(name)
+        const ns = this.resolver.resolveNamespace(name.split('.'))
+        const file = this.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 = util.unlocalize(
+            this.resolver.trimNamespace(util.getPluralAnnotation(entity) ? util.plural4(entity, false) : name)
+        )
+        const singular = util.unlocalize(util.singular4(entity, true))
+        if (singular === plural) {
+            plural += '_'
+            this.logger.warning(
+                `Derived singular and plural forms for '${singular}' are the same. This usually happens when your CDS entities are named following singular flexion. Consider naming your entities in plural or providing '@singular:'/ '@plural:' annotations to have a clear distinction between the two. Plural form will be renamed to '${plural}' to avoid compilation errors within the output.`
+            )
+        }
+        if (singular in this.csn.definitions) {
+            this.logger.error(
+                `Derived singular '${singular}' for your entity '${name}', already exists. The resulting types will be erronous. Please consider using '@singular:'/ '@plural:' annotations in your model to resolve this collision.`
+            )
+        }
+        file.addClass(singular, name)
+        file.addClass(plural, name)
+
+        const parent = this.resolver.resolveParent(entity.name)
+        const buffer =
+            parent && parent.kind === 'entity'
+                ? file.getSubNamespace(this.resolver.trimNamespace(parent.name))
+                : file.classes
+
+        // we can't just use "singular" here, as it may have the subnamespace removed:
+        // "Books.text" is just "text" in "singular". Within the inflected exports we need
+        // to have Books.texts = Books.text, so we derive the singular once more without cutting off the ns.
+        // Directly deriving it from the plural makes sure we retain any parent namespaces of kind "entity",
+        // which would not be possible while already in singular form, as "Book.text" could not be resolved in CSN.
+        file.addInflection(util.singular4(plural), plural, clean)
+        if ('doc' in entity) {
+            docify(entity.doc).forEach((d) => buffer.add(d))
+        }
+
+        this._aspectify(name, entity, file.classes, singular)
+
+        // PLURAL
+        if (plural.includes('.')) {
+            // Foo.text -> namespace Foo { class text { ... }}
+            plural = plural.split('.').pop()
+        }
+        // plural can not be a type alias to $singular[] but needs to be a proper class instead,
+        // so it can get passed as value to CQL functions.
+        buffer.add(`export class ${plural} extends Array<${singular}> {}`)
+        buffer.add('')
+    }
+
+    #printFunction(name, func) {
+        // 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 params = func.params
+            ? Object.entries(func.params).map(([pname, ptype]) => [
+                  pname,
+                  this.resolver.resolveAndRequire(ptype, file).typeName,
+              ])
+            : []
+        const returns = this.resolver.resolveAndRequire(func.returns, file).typeName
+        file.addFunction(name.split('.').at(-1), params, returns)
+    }
+
+    #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 params = action.params
+            ? Object.entries(action.params).map(([pname, ptype]) => [
+                  pname,
+                  this.resolver.resolveAndRequire(ptype, file).typeName,
+              ])
+            : []
+        const returns = this.resolver.resolveAndRequire(action.returns, file).typeName
+        file.addAction(name.split('.').at(-1), params, returns)
+    }
+
+    #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) {
+            // in case of strings, wrap in quotes and fallback to key to make sure values are attached for every key
+            const val = (k,v) => type.type === 'cds.String' ? `"${v ?? k}"` : v
+            file.addEnum(
+                name,
+                clean,
+                Object.entries(type.enum).map(([k, v]) => [k, val(k, v.val)])
+            )
+        } else {
+            // alias
+            file.addType(name, clean, this.resolver.resolveAndRequire(type, file).typeName)
+        }
+        // TODO: annotations not handled yet
+    }
+
+    #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)
+        // 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.
+        file.addClass(clean, name)
+        file.aspects.add(`// the following represents the CDS aspect '${clean}'`)
+        this._aspectify(name, aspect, file.aspects, clean)
+    }
+
+    /**
+     * Visits a single entity from the CSN's definition field.
+     * Will call #printEntity or #printAction based on the entity's kind.
+     * @param {string} name name of the entity, fully qualified as is used in the definition field.
+     * @param {CSN} entity CSN data belonging to the entity to perform lookups in.
+     */
+    visitEntity(name, entity) {
+        switch (entity.kind) {
+            case 'entity':
+                this.#printEntity(name, entity)
+                break
+            case 'action':
+                this.#printFunction(name, entity)
+                break
+            case 'function':
+                this.#printAction(name, entity)
+                break
+            case 'type':
+                this.#printType(name, entity)
+                break
+            case 'aspect':
+                this.#printAspect(name, entity)
+                break
+            default:
+                this.logger.error(`Unhandled entity kind '${entity.kind}'.`)
+        }
+    }
+
+    /**
+     * A self reference is a property that references the class it appears in.
+     * They need to be detected on CDS level, as the emitted TS types will try to
+     * refer to refer to types via their alias that hides the aspectification.
+     * If we attempt to directly refer to this alias while it has not been fully created,
+     * that will result in a TS error.
+     * @param {String} entityName
+     * @returns {boolean} true, if `entityName` refers to the surrounding class
+     * @example
+     * ```ts
+     * class TreeNode {
+     *   value: number
+     *   parent: TreeNode // <- self reference
+     * }
+     * ```
+     */
+    isSelfReference(entityName) {
+        return entityName === this.contexts.at(-1)?.entity
+    }
+
+    /**
+     * Visits a single element in an entity.
+     * @param {string} name name of the element
+     * @param {import('./components/resolver').CSN} element CSN data belonging to the the element.
+     * @param {SourceFile} file the namespace file the surrounding entity is being printed into.
+     * @param {Buffer} buffer buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @returns @see InlineDeclarationResolver.visitElement
+     */
+    visitElement(name, element, file, buffer) {
+        return this.inlineDeclarationResolver.visitElement(name, element, file, buffer)
+    }
+}
+
+module.exports = {
+    Visitor
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.2.5-beta.1",
+  "version": "0.4.0",
   "description": "Generates .ts files for a CDS model to receive code completion in VS Code",
   "main": "index.js",
   "homepage": "https://cap.cloud.sap/",