@cap-js/cds-typer 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,7 +4,7 @@ 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.7.1 - TBD
+## Version 0.9.1 - TBD
 
 ### Changed
 
@@ -12,6 +12,28 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Fixed
 
+## Version 0.9.0 - 2023-09-08
+
+### Changed
+
+### Added
+- Support for drafts via `@odata.draft.enabled` annotation
+
+### Fixed
+- Foreign keys are now propagated more than one level (think: `x_ID_ID_ID`)
+
+
+## Version 0.8.0 - 2023-09-05
+
+### Changed
+
+### Added
+
+### Fixed
+- Foreign keys that are inherited via aspects are now also generated in addition to the resolved property (see 0.7.0)
+- Explicitly annotated `@singular` and `@plural` names are now properly used in generated _index.js_ files
+
+
 ## Version 0.7.0 - 2023-08-22
 
 ### Changed

package/lib/csn.js

@@ -0,0 +1,267 @@
+const annotation = '@odata.draft.enabled'
+
+class DraftUnroller {
+    /** @type {Set<string>} */
+    #positives = new Set()
+    /** @type {{[key: string]: boolean}} */
+    #draftable = {}
+    /** @type {{[key: string]: string}} */
+    #projections 
+    /** @type {object[]} */
+    #entities
+    #csn
+    set csn(c) {
+        this.#csn = c
+        this.#entities = Object.values(c.definitions)
+        this.#projections = this.#entities.reduce((pjs, entity) => {
+            if (entity.projection) {
+                pjs[entity.name] = entity.projection.from.ref[0]
+            }
+            return pjs
+        }, {})
+    }
+    get csn() { return this.#csn }
+
+    /**
+     * @param entity {object | string} - entity to set draftable annotation for.
+     * @param value {boolean} - whether the entity is draftable.
+     */
+    #setDraftable(entity, value) { 
+        if (typeof entity === 'string') entity = this.#getDefinition(entity)
+        entity[annotation] = value
+        this.#draftable[entity.name] = value
+        if (value) {
+            this.#positives.add(entity.name)
+        } else {
+            this.#positives.delete(entity.name)
+        }
+    }
+
+    /**
+     * @param entity {object | string} - entity to look draftability up for.
+     * @returns {boolean}
+     */
+    #getDraftable(entity) { 
+        if (typeof entity === 'string') entity = this.#getDefinition(entity)
+        return this.#draftable[entity.name] ??= this.#propagateInheritance(entity) 
+    }
+
+    /**
+     * @param name {string} - name of the entity.
+     */
+    #getDefinition(name) { return this.csn.definitions[name] }
+
+    /**
+     * Propagate draft annotations through inheritance (includes).
+     * The latest annotation through the inheritance chain "wins".
+     * Annotations on the entity itself are always queued last, so they will always be decisive over ancestors.
+     * 
+     * @param entity {object} - entity to pull draftability from its parents.
+     */
+    #propagateInheritance(entity) {
+        const annotations = (entity.includes ?? []).map(parent => this.#getDraftable(parent))
+        annotations.push(entity[annotation])
+        this.#setDraftable(entity, annotations.filter(a => a !== undefined).at(-1) ?? false)
+    }
+
+    /**
+     * Propagate draft-enablement through projections.
+     */
+    #propagateProjections() {
+        const propagate = (from, to) => {
+            do {
+                this.#setDraftable(to, this.#getDraftable(to) || this.#getDraftable(from))
+                from = to
+                to = this.#projections[to]
+            } while (to)
+        }
+
+        for (let [projection, target] of Object.entries(this.#projections)) {
+            propagate(projection, target)
+            propagate(target, projection)
+        }
+    }
+
+    /**
+     * If an entity E is draftable and contains any composition of entities,
+     * then those entities also become draftable. Recursively.
+     * 
+     * @param entity {object} - entity to propagate all compositions from.
+     */
+    #propagateCompositions(entity) {
+        if (!this.#getDraftable(entity)) return
+
+        for (const comp of Object.values(entity.compositions ?? {})) {
+            const target = this.#getDefinition(comp.target)
+            const current = this.#getDraftable(target)
+            if (!current) {
+                this.#setDraftable(target, true)
+                this.#propagateCompositions(target)
+            }
+        }
+    }
+
+    unroll(csn) {
+        this.csn = csn
+
+        // inheritance
+        for (const entity of this.#entities) {
+            this.#propagateInheritance(entity)
+        }
+
+        // transitivity through compositions
+        // we have to do this in a second pass, as we only now know which entities are draft-enables themselves
+        for (const entity of this.#entities) {
+            this.#propagateCompositions(entity)
+        }
+
+        this.#propagateProjections()
+    }
+}
+
+// note to self: following doc uses ＠ homoglyph instead of @, as the latter apparently has special semantics in code listings
+/**
+ * We are unrolling the @odata.draft.enabled annotations into related entities manually.
+ * This includes three scenarios:
+ * 
+ * (a) aspects via `A: B`, where `B` is draft enabled.
+ * Note that when an entity extends two other entities of which one has drafts enabled and
+ * one has not, then the one that is later in the list of mixins "wins":
+ * @example sdasd
+ * ```ts
+ * ＠odata.draft.enabled true
+ * entity T {}
+ * ＠odata.draft.enabled false
+ * entity F {}
+ * entity A: T,F {}  // draft not enabled
+ * entity B: F,T {}  // draft enabled
+ * ```
+ * 
+ * (b) Draft enabled projections make the entity we project on draft enabled.
+ * @example
+ * ```ts
+ * ＠odata.draft.enabled: true
+ * entity A as projection on B {}
+ * entity B {}  // draft enabled
+ * ```
+ * 
+ * (c) Entities that are draft enabled propagate this property down through compositions:
+ * 
+ * ```ts
+ * ＠odata.draft.enabled: true
+ * entity A {
+ *   b: Composition of B
+ * }
+ * entity B {}  // draft enabled
+ * ```
+ */
+function unrollDraftability(csn) {
+    new DraftUnroller().unroll(csn)
+}
+
+/**
+ * Propagates keys elements through the CSN. This includes
+ * 
+ * (a) keys that are explicitly declared as key in an entity
+ * (b) keys from aspects the entity extends
+ * 
+ * This explicit propagation is required to add foreign key relations
+ * to referring entities.
+ * 
+ * @example
+ * ```cds
+ * entity A: cuid { key name: String; }
+ * entity B { ref: Association to one A }
+ * ```
+ * must yield
+ * ```ts
+ * class A { 
+ *   ID: UUID // inherited from cuid
+ *   name: String;
+ * } 
+ * class B {
+ *   ref: Association.to<A>
+ *   ref_ID: UUID
+ *   ref_name: String;
+ * }
+ * ```
+ * @returns {{[key: string]: object}}
+ */
+function propagateForeignKeys(csn) {
+    for (const element of Object.values(csn.definitions)) {
+        Object.defineProperty(element, 'keys', {
+            get: function () {
+                // cached access to all immediately defined _and_ inherited keys.
+                // They need to be explicitly accessible in subclasses to generate
+                // foreign key fields from Associations/ Compositions.
+                if (!Object.hasOwn(this, '__keys')) {
+                    const ownKeys = Object.entries(this.elements ?? {}).filter(([,el]) => el.key === true)
+                    const inheritedKeys = this.includes?.flatMap(parent => Object.entries(csn.definitions[parent].keys)) ?? []
+                    // not sure why, but .associations contains both Associations, as well as Compositions in CSN.
+                    // (.compositions contains only Compositions, if any)
+                    const remoteKeys = Object.entries(this.associations ?? {})
+                        .filter(([,{key}]) => key)  // only follow associations that are keys, that way we avoid cycles
+                        .flatMap(([kname, key]) => Object.entries(csn.definitions[key.target].keys)
+                            .map(([ckname, ckey]) => [`${kname}_${ckname}`, ckey])) 
+
+                    this.__keys = Object.fromEntries(ownKeys
+                        .concat(inheritedKeys)
+                        .concat(remoteKeys)
+                        .filter(([,ckey]) => !ckey.target)  // discard keys that are Associations. Those are already part of .elements
+                    )
+                }
+                return this.__keys
+            }
+        })
+    }
+}
+
+/** 
+* 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.
+* @deprecated since we use the xtended flavour for CSN, we don't need to fix this anymore
+*/
+function propagateInflectionAnnotations(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++
+        }
+    }
+}
+
+function amendCSN(csn) {
+    unrollDraftability(csn)
+    propagateForeignKeys(csn)
+}
+
+module.exports = { amendCSN }

package/lib/file.js

@@ -335,6 +335,9 @@ class SourceFile extends File {
                     .flatMap(([singular, plural, original]) => Array.from(new Set([
                         `module.exports.${singular} = csn.${original}`,
                         `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}`
                     ])))
             ) // singular -> plural aliases

package/lib/util.js

@@ -184,48 +184,6 @@ 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,
@@ -234,6 +192,5 @@ module.exports = {
     singular4,
     plural4,
     parseCommandlineArgs,
-    deepMerge,
-    fixCSN
+    deepMerge
 }

package/lib/visitor.js

@@ -2,6 +2,7 @@
 
 const util = require('./util')
 
+const { amendCSN } = require('./csn')
 const { SourceFile, baseDefinitions, Buffer } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./components/resolver')
@@ -59,6 +60,7 @@ class Visitor {
      * @param {VisitorOptions} options
      */
     constructor(csn, options = {}, logger = new Logger()) {
+        amendCSN(csn)
         this.options = { ...defaults, ...options }
         this.logger = logger
         this.csn = csn
@@ -127,13 +129,21 @@ class Visitor {
         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)
+
             // make foreign keys explicit
-            for (const [fkname, fkelement] of Object.entries(element.foreignKeys ?? {})) {
-                this.visitElement(`${ename}_${fkname}`, fkelement, file, buffer)
+            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 Object.entries(this.csn.definitions[element.target]?.keys ?? {})) {
+                    this.visitElement(`${ename}_${kname}`, kelement, file, buffer)
+                }
             }
-        }
+        }      
+
         for (const [aname, action] of Object.entries(entity.actions ?? {})) {
             buffer.add(
                 SourceFile.stringifyLambda({
@@ -167,11 +177,19 @@ class Visitor {
                 `${baseDefinitions.path.asIdentifier()}.Entity`
             )
 
-        buffer.add(`export class ${identSingular(clean)} extends ${rhs} {}`)
+        buffer.add(`export class ${identSingular(clean)} extends ${rhs} {${this.#staticClassContents(clean, entity).join('\n')}}`)
         //buffer.add(`export type ${clean} = InstanceType<typeof ${identSingular(clean)}>`)
         this.contexts.pop()
     }
 
+    #isDraftEnabled(entity) {
+        return entity['@odata.draft.enabled'] === true
+    }
+
+    #staticClassContents(clean, entity) {
+        return this.#isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : [] 
+    }
+
     #printEntity(name, entity) {
         const clean = this.resolver.trimNamespace(name)
         const ns = this.resolver.resolveNamespace(name.split('.'))
@@ -207,7 +225,8 @@ class Visitor {
         // 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)
+        // edge case: @singular annotation present. singular4 will take care of that.
+        file.addInflection(util.singular4(entity, true), plural, clean)
         if ('doc' in entity) {
             docify(entity.doc).forEach((d) => buffer.add(d))
         }
@@ -221,7 +240,7 @@ class Visitor {
         }
         // 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(`export class ${plural} extends Array<${singular}> {${this.#staticClassContents(singular, entity).join('\n')}}`)
         buffer.add('')
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -22,10 +22,7 @@
     "doc:clean": "rm -rf ./doc",
     "doc:prepare": "npm run doc:clean && mkdir -p doc/types",
     "doc:typegen": "./node_modules/.bin/tsc ./lib/*.js  --skipLibCheck --declaration --allowJs --emitDeclarationOnly --outDir doc/types && cd doc/types && tsc --init",
-    "doc:html": "npm run doc:typegen && ./node_modules/.bin/typedoc 'doc/types/**/*.d.ts' --entryPointStrategy expand --out doc/html --tsconfig doc/types/tsconfig.json",
-    "doc:md": "npm run doc:typegen && ./node_modules/.bin/typedoc --plugin typedoc-plugin-markdown 'doc/types/compile.d.ts' --out doc/md --tsconfig doc/types/tsconfig.json",
-    "doc:cli": "npm run cli -- --help > ./doc/cli.txt",
-    "doc:full": "npm run doc:prepare && npm run doc:html && npm run doc:cli"
+    "doc:cli": "npm run cli -- --help > ./doc/cli.txt"
   },
   "files": [
     "lib/",
@@ -43,12 +40,11 @@
     "@sap/cds": ">=6"
   },
   "devDependencies": {
+    "acorn": "^8.10.0",
     "eslint": "^8.15.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.0.0",
     "jest": "^29",
-    "typedoc": "^0.24.8",
-    "typedoc-plugin-markdown": "^3.15.3",
     "typescript": ">=4.6.4"
   },
   "jest": {