@cap-js/cds-typer 0.8.0 → 0.10.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.8.1 - TBD
+## Version 0.10.1 - TBD
 
 ### Changed
 
@@ -12,6 +12,25 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Fixed
 
+## Version 0.10.0 - 2023-09-21
+
+### Changed
+- Actions and functions are now attached to a static `.actions` property of each generated class. This reflects the runtime behaviour better than the former way of generating instance methods
+
+### Added
+
+### 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
 

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

@@ -127,18 +127,34 @@ class SourceFile extends File {
      * @returns {string} - the stringified lambda
      * @example
      * ```js
-     * stringifyLambda({parameters: [['p','T']]}  // (p: T) => any
-     * stringifyLambda({name: 'f', parameters: [['p','T']]}  // f: (p: T) => any
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'}  // f: (p: T) => number
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number', initialiser: '_ => 42'}  // f: (p: T) => string = _ => 42
+     * // note: these samples are actually simplified! See below.
+     * stringifyLambda({parameters: [['p','T']]})  // f: { (p: T): any, ... }
+     * stringifyLambda({name: 'f', parameters: [['p','T']]})  // f: { (p: T) => any, ...  }
+     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // f: { (p: T) => number, ...  }
+     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number', initialiser: '_ => 42'})  // f: { (p: T): string = _ => 42, ...  }
+     * ```
+     * 
+     * The generated string will not be just the signature of the function. Instead, it will be an object offering a callable signature.
+     * On top of that, it will also expose a property `__parameters`, which is an object reflecting the functions parameters.
+     * The reason for this is that the CDS runtime actually treats the function parameters as a named object. This can not be rectified via
+     * type magic, as parameter names do not exist on type level. So we can not use these names to reuse them as object properties.
+     * Instead, we generate this utility object for the runtime to use:
      * 
+     * @example
+     * ```js
+     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
      * ```
      */
-    static stringifyLambda({name, parameters=[], returns='any', initialiser}) {
-        const signature = `(${parameters.map(([n, t]) => `${n}: ${t}`).join(', ')}) => ${returns}`
-        const prefix = name ? `${name}: `: ''
+    static stringifyLambda({name, parameters=[], returns='any', initialiser, isStatic=false}) {
+        const parameterTypes = parameters.map(([n, t]) => `${n}: ${t}`).join(', ')
+        const callableSignature = `(${parameterTypes}): ${returns}`
+        let prefix = name ? `${name}: `: ''
+        if (prefix && isStatic) {
+            prefix = `static ${prefix}`
+        }
         const suffix = initialiser ? ` = ${initialiser}` : ''
-        return prefix + signature + suffix
+        const lambda = `{ ${callableSignature}, __parameters: {${parameterTypes}}, __returns: ${returns} }`
+        return prefix + lambda + suffix
     }
 
     /**

package/lib/util.js

@@ -184,66 +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) {
-    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.fromEntries(Object.entries(this.elements ?? {}).filter(([,el]) => el.key === true))
-                    const inheritedKeys = this.includes?.flatMap(parent => csn.definitions[parent].keys) ?? []
-                    this.__keys = inheritedKeys.reduce((ks, ps) => ({...ps, ...ks}), ownKeys)
-                }
-                return this.__keys
-            }
-        })
-    }
-
-    // FIXME: delete after merge with draft-enablement PR
-    return
-    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,
@@ -252,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,7 +60,7 @@ class Visitor {
      * @param {VisitorOptions} options
      */
     constructor(csn, options = {}, logger = new Logger()) {
-        util.fixCSN(csn)
+        amendCSN(csn)
         this.options = { ...defaults, ...options }
         this.logger = logger
         this.csn = csn
@@ -128,8 +129,10 @@ 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
             if ('target' in element) {
                 // lookup in cds.definitions can fail for inline structs.
@@ -139,21 +142,27 @@ class Visitor {
                     this.visitElement(`${ename}_${kname}`, kelement, file, buffer)
                 }
             }
-        }
+        }      
+
+        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 this['${aname}']`
+                    returns: action.returns ? this.resolver.resolveAndRequire(action.returns, file).typeName : 'any'
+                    //initialiser: `undefined as unknown as typeof ${clean}.${aname}`,
                 })
             )
         }
         buffer.outdent()
-        buffer.add('};')
+        buffer.add('}') // end of actions
+
+        buffer.outdent()
+        buffer.add('};') // end of generated class
         buffer.outdent()
-        buffer.add('}')
+        buffer.add('}')  // end of aspect
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
@@ -173,11 +182,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('.'))
@@ -228,7 +245,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.8.0",
+  "version": "0.10.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/",
@@ -48,8 +45,6 @@
     "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": {