@cap-js/cds-typer 0.26.0 → 0.28.0

package/lib/components/wrappers.js

@@ -3,6 +3,41 @@
 // this was derived from baseDefinitions before, but caused a circular dependency
 const base = '__'
 
+/**
+ * Wraps type into the Key type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKey = t => `${base}.Key<${t}>`
+
+/**
+ * Wraps type into KeysOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createKeysOf = t => `${base}.KeysOf<${t}>`
+
+/**
+ * Wraps type into DraftOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createDraftOf = t => `${base}.DraftOf<${t}>`
+
+/**
+ * Wraps type into DraftsOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createDraftsOf = t => `${base}.DraftsOf<${t}>`
+
+/**
+ * Wraps type into ElementsOf type.
+ * @param {string} t - the type name.
+ * @returns {string}
+ */
+const createElementsOf = t => `${base}.ElementsOf<${t}>`
+
 /**
  * Wraps type into association to scalar.
  * @param {string} t - the singular type name.
@@ -84,8 +119,20 @@ const docify = doc => {
     return ['/**'].concat(lines.map(line => `* ${line}`)).concat(['*/'])
 }
 
+/**
+ * Wraps a string in single quotes. No escaping is done, so use with caution.
+ * @param {string} s - the string to wrap.
+ * @returns {string}
+ */
+const stringIdent = s => `'${s}'`
+
 module.exports = {
     createArrayOf,
+    createDraftOf,
+    createDraftsOf,
+    createKey,
+    createKeysOf,
+    createElementsOf,
     createObjectOf,
     createPromiseOf,
     createUnionOf,
@@ -94,5 +141,6 @@ module.exports = {
     createCompositionOfOne,
     createCompositionOfMany,
     deepRequire,
-    docify
+    docify,
+    stringIdent
 }

package/lib/config.js

@@ -0,0 +1,118 @@
+const cds = require('@sap/cds')
+const { camelToSnake } = require('./util')
+
+/**
+ * Makes properties of an object accessible in both camelCase and snake_case.
+ * Snake_case gets precedence over camelCase.
+ * @template T
+ * @param {T} target - The object to proxy.
+ * @returns {T} - The proxied object.
+ */
+const camelSnakeHybrid = target => {
+    // @ts-expect-error - expecting target to be of type {}, which is not T (same for following)
+    const proxy = new Proxy(target, {
+        get(target, prop) {
+            // @ts-expect-error
+            return target[camelToSnake(prop)] ?? target[prop]
+        },
+        set(target, p, v) {
+            // @ts-expect-error
+            target[camelToSnake(p)] = v
+            return true
+        }
+    })
+    // need to make sure all properties are initially available in snake_case
+    // @ts-expect-error
+    for (const [k,v] of Object.entries(target)) {
+        // @ts-expect-error
+        proxy[k] = v
+    }
+    // @ts-expect-error
+    return proxy
+}
+class Config {
+    static #defaults = {
+        propertiesOptional: true,
+        useEntitiesProxy: false,
+        inlineDeclarations: 'flat',
+        outputDirectory: '.'
+    }
+
+    values = undefined
+    proxy = undefined
+
+    init () {
+        this.values = {...Config.#defaults, ...(cds.env.typer ?? {})}
+        this.proxy = camelSnakeHybrid(this.values)
+    }
+
+    constructor() {
+        // proxy around config still allows arbitrary property access:
+        // require('config').configuration.logLevel = 'warn' will work
+        // eslint-disable-next-line no-constructor-return
+        return new Proxy(this, {
+            get(target, prop) {
+                // lazy loading of cds.env
+                // if we don't do this, configuration will load cds.env whenever it is
+                // first imported anywhere (even by proxy from, say, cli.js).
+                // So we don't get to modify cds.env before that, which is important
+                // in cds-build.js.
+                // FIXME: revisit. This is horrible.
+                if (target.values === undefined) target.init()
+                return target[prop] ?? target.proxy[prop]
+            },
+            set(target, p, v) {
+                if (target.values === undefined) target.init()
+
+                // this.value, this.proxy etc should not be forwarded to the wrapped values
+                if (target[p]) {
+                    target[p] = v
+                } else {
+                    target.proxy[p] = v
+                }
+                return true
+            }
+        })
+    }
+
+    /**
+     * @param {string} key - The key to set.
+     * @param {any} value - The value to set
+     */
+    setOne (key, value) {
+        this.proxy[key] = value
+    }
+
+    /**
+     * @param {object} props - The properties to set.
+     */
+    setMany (props) {
+        for (const [k,v] of Object.entries(props)) {
+            this.proxy[k] = v
+        }
+    }
+
+    /**
+     * Resets the config value and sets all its values from another passed
+     * config object. This allows to keep the reference to the same object.
+     * @param {Config} config - Another config object to set all config entries from.
+     */
+    setFrom (config) {
+        this.values = camelSnakeHybrid({})
+        this.setMany(config.values)
+    }
+
+    clone () {
+        const res = new Config()
+        res.init()
+        res.setMany(this.values)
+        return res
+    }
+}
+
+module.exports = {
+    camelSnakeHybrid,
+    /** @type {import('./typedefs').config.Configuration} */
+    // @ts-ignore
+    configuration: new Config()
+}

package/lib/csn.js

@@ -1,4 +1,8 @@
-const annotation = '@odata.draft.enabled'
+const { LOG } = require('./logging')
+
+const DRAFT_ENABLED_ANNO = '@odata.draft.enabled'
+/** @type {string[]} */
+const draftEnabledEntities = []
 
 /** @typedef {import('./typedefs').resolver.CSN} CSN */
 /** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
@@ -40,9 +44,9 @@ const isUnresolved = entity => entity._unresolved === true
 const isCsnAny = entity => entity?.constructor?.name === 'any'
 
 /**
- * @param {EntityCSN} entity - the entity
+ * @param {string} fq - the fqn of an entity
  */
-const isDraftEnabled = entity => entity['@odata.draft.enabled'] === true
+const isDraftEnabled = fq => draftEnabledEntities.includes(fq)
 
 /**
  * @param {EntityCSN} entity - the entity
@@ -87,183 +91,151 @@ const getProjectionTarget = entity => isProjection(entity)
     ? entity.projection?.from?.ref?.[0]
     : undefined
 
-class DraftUnroller {
-    /** @type {Set<string>} */
-    #positives = new Set()
-    /** @type {{[key: string]: boolean}} */
-    #draftable = {}
-    /** @type {{[key: string]: string}} */
-    #projections = {}
+class DraftEnabledEntityCollector {
     /** @type {EntityCSN[]} */
-    #entities = []
+    #draftRoots = []
+    /** @type {string[]} */
+    #serviceNames = []
     /** @type {CSN | undefined} */
     #csn
-    set csn(c) {
-        this.#csn = c
-        if (c === undefined) return
-        this.#entities = Object.values(c.definitions)
-        this.#projections = this.#entities.reduce((pjs, entity) => {
-            if (isProjection(entity)) {
-                // @ts-ignore - we know that entity is a projection here
-                pjs[entity.name] = getProjectionTarget(entity)
-            }
-            return pjs
-        }, {})
-    }
-    get csn() { return this.#csn }
+    #compileError = false
 
     /**
-     * @param {EntityCSN | string} entityOrFq - entity to set draftable annotation for.
-     * @param {boolean} value - whether the entity is draftable.
+     * @returns {string[]}
      */
-    #setDraftable(entityOrFq, value) {
-        const entity = typeof entityOrFq === 'string'
-            ? this.#getDefinition(entityOrFq)
-            : entityOrFq
-        if (!entity) return  // inline definition -- not found in definitions
-        entity[annotation] = value
-        this.#draftable[entity.name] = value
-        if (value) {
-            this.#positives.add(entity.name)
-        } else {
-            this.#positives.delete(entity.name)
-        }
+    #getServiceNames() {
+        return Object.values(this.#csn?.definitions ?? {}).filter(d => d.kind === 'service').map(d => d.name)
     }
 
     /**
-     * @param {EntityCSN | string} entityOrFq - entity to look draftability up for.
-     * @returns {boolean}
+     * @returns {EntityCSN[]}
      */
-    #getDraftable(entityOrFq) {
-        const entity = typeof entityOrFq === 'string'
-            ? this.#getDefinition(entityOrFq)
-            : entityOrFq
-        // assert(typeof entity !== 'string')
-        const name = entity?.name ?? entityOrFq
-        // @ts-expect-error - .name not being present means entityOrFq is a string, so name is always a string and therefore a valid index
-        return this.#draftable[name] ??= this.#propagateInheritance(entity)
+    #collectDraftRoots() {
+        return Object.values(this.#csn?.definitions ?? {}).filter(
+            d => isEntity(d) && this.#isDraftEnabled(d) && this.#isPartOfAnyService(d.name)
+        )
     }
 
     /**
-     * FIXME: could use EntityRepository here
-     * @param {string} name - name of the entity.
-     * @returns {EntityCSN}
-     */
-    // @ts-expect-error - poor man's #getDefinitionOrThrow. We are always sure name is a valid key
-    #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 {EntityCSN | undefined} entity - entity to pull draftability from its parents.
+     * @param {string} entityName - entity to check
+     * @returns {boolean} `true` if entity is part an service
      */
-    #propagateInheritance(entity) {
-        if (!entity) return
-        /** @type {(boolean | undefined)[]} */
-        const annotations = (entity.includes ?? []).map(parent => this.#getDraftable(parent))
-        annotations.push(entity[annotation])
-        this.#setDraftable(entity, annotations.filter(a => a !== undefined).at(-1) ?? false)
+    #isPartOfAnyService(entityName) {
+        return this.#serviceNames.some(s => entityName.startsWith(s))
     }
 
     /**
-     * Propagate draft-enablement through projections.
+     * Collect all entities that are transitively reachable via compositions from `entity` into `draftNodes`.
+     * Check that no entity other than the root node has `@odata.draft.enabled`
+     * @param {EntityCSN} entity -
+     * @param {string} entityName -
+     * @param {EntityCSN} rootEntity - root entity where composition traversal started.
+     * @param {Record<string,EntityCSN>} draftEntities - Dictionary of entitys
      */
-    #propagateProjections() {
-        /**
-         * @param {string} from - entity to propagate draftability from.
-         * @param {string} to - entity to propagate draftability to.
-         */
-        const propagate = (from, to) => {
-            do {
-                this.#setDraftable(to, this.#getDraftable(to) || this.#getDraftable(from))
-                from = to
-                to = this.#projections[to]
-            } while (to)
-        }
+    #collectDraftEntitiesInto(entity, entityName, rootEntity, draftEntities) {
+        draftEntities[entityName] = entity
+
+        for (const elem of Object.values(entity.elements ?? {})) {
+            if (!elem.target || elem.type !== 'cds.Composition') continue
+
+            const draftEntity = this.#csn?.definitions[elem.target]
+            const draftEntityName = elem.target
+
+            if (!draftEntity) {
+                throw new Error(`Expecting target to be resolved: ${JSON.stringify(elem, null, 2)}`)
+            }
+
+            if (!this.#isPartOfAnyService(draftEntityName)) {
+                LOG.warn(`Ignoring draft entity for composition target ${draftEntityName} because it is not part of a service`)
+                continue
+            }
+
+            if (draftEntity !== rootEntity && this.#isDraftEnabled(draftEntity)) {
+                this.#compileError = true
+                LOG.error(`Composition in draft-enabled entity can't lead to another entity with "@odata.draft.enabled" (in entity: "${entityName}"/element: ${elem.name})!`)
+                delete draftEntities[draftEntityName]
+                continue
+            }
 
-        for (let [projection, target] of Object.entries(this.#projections)) {
-            propagate(projection, target)
-            propagate(target, projection)
+            if (!this.#isDraftEnabled(draftEntity) && !draftEntities[draftEntityName]) {
+                this.#collectDraftEntitiesInto(draftEntity, draftEntityName, rootEntity, draftEntities)
+            }
         }
     }
 
     /**
-     * If an entity E is draftable and contains any composition of entities,
-     * then those entities also become draftable. Recursively.
-     * @param {EntityCSN} entity - entity to propagate all compositions from.
+     * @param {EntityCSN} entity - entity to check
+     * @returns {boolean}
      */
-    #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)
-            }
-        }
+    #isDraftEnabled(entity) {
+        return entity[DRAFT_ENABLED_ANNO] === true
     }
 
     /** @param {CSN} csn - the full csn  */
-    unroll(csn) {
-        this.csn = csn
+    run(csn) {
+        if (!csn) return
 
-        // inheritance
-        for (const entity of this.#entities) {
-            this.#propagateInheritance(entity)
-        }
+        this.#csn = csn
+        this.#serviceNames = this.#getServiceNames()
+        this.#draftRoots = this.#collectDraftRoots()
 
-        // 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)
-        }
+        for (const draftRoot of this.#draftRoots) {
+            /** @type {Record<string,EntityCSN>} */
+            const draftEntities = {}
+            this.#collectDraftEntitiesInto(draftRoot, draftRoot.name, draftRoot, draftEntities)
 
-        this.#propagateProjections()
+            for (const draftNode of Object.values(draftEntities)) {
+                draftEnabledEntities.push(draftNode.name)
+            }
+        }
+        /**
+         * If an unreconcilable draft model error occurred, the whole type generation
+         * will be cancelled. This aligns with the behavior of commands like e.g.
+         * - cds compile srv -4 odata
+         * - cds compile srv -4 sql
+         * - cds watch
+         */
+        if (this.#compileError) throw new Error('Compilation of model failed')
     }
 }
 
 // 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:
+ * We collect all entities that are draft enabled.
+ * (@see `@sap/cds-compiler/lib/transform/draft/db.js#generateDraft`)
  *
- * (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":
+ * This includes thwo scenarios:
+ *  - (a) Entities that are part of a service and have the annotation ＠odata.draft.enabled
+ *  - (b) Entities that are draft enabled propagate this property down through compositions.
+ *        NOTE: The compositions themselves must not be draft enabled, otherwise no draft entity will be generated for them
  * @param {any} csn - the entity
  * @example
- * ```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
- * ```
+ * (a)
+ * ```cds
+ * // service.cds
+ * service MyService {
+ *   ＠odata.draft.enabled true
+ *   entity A {}
  *
- * (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
+ *   ＠odata.draft.enabled true
+ *   entity B {}
+ * }
  * ```
- *
- * (c) Entities that are draft enabled propagate this property down through compositions:
- *
- * ```ts
- * ＠odata.draft.enabled: true
- * entity A {
- *   b: Composition of B
+ * @example
+ * (b)
+ * ```cds
+ * // service.cds
+ * service MyService {
+ *   ＠odata.draft.enabled: true
+ *   entity A {
+ *     b: Composition of B
+ *   }
+ *   entity B {}  // draft enabled
  * }
- * entity B {}  // draft enabled
  * ```
  */
-function unrollDraftability(csn) {
-    new DraftUnroller().unroll(csn)
+function collectDraftEnabledEntities(csn) {
+    new DraftEnabledEntityCollector().run(csn)
 }
 
 /**
@@ -320,15 +292,6 @@ function propagateForeignKeys(csn) {
     }
 }
 
-/**
- *
- * @param {any} csn - complete csn
- */
-function amendCSN(csn) {
-    unrollDraftability(csn)
-    propagateForeignKeys(csn)
-}
-
 /**
  * @param {EntityCSN} entity - the entity
  */
@@ -349,7 +312,7 @@ const getProjectionAliases = entity => {
 }
 
 module.exports = {
-    amendCSN,
+    collectDraftEnabledEntities,
     isView,
     isProjection,
     isViewOrProjection,

package/lib/file.js

@@ -8,11 +8,11 @@ const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
 const { proxyAccessFunction } = require('./components/javascript')
 const { createObjectOf } = require('./components/wrappers')
+const { configuration } = require('./config')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
 /** @typedef {import('./typedefs').file.Namespace} Namespace */
-/** @typedef {import('./typedefs').file.FileOptions} FileOptions */
 
 class File {
     /**
@@ -109,11 +109,9 @@ class Library extends File {
 class SourceFile extends File {
     /**
      * @param {string | Path} path - path to the file
-     * @param {FileOptions} [options] - options for file output
      */
-    constructor(path, options) {
+    constructor(path) {
         super()
-        this.options = options ?? { useEntitiesProxy: false }
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
         /** @type {{[key:string]: any}} */
@@ -159,7 +157,7 @@ class SourceFile extends File {
      * @param {boolean} [options.isStatic] - whether the lambda is static
      * @param {{positional?: boolean, named?: boolean}} [options.callStyles] - whether to generate positional and/or named call styles
      * @param {string[]?} [options.doc] - documentation for the operation
-     * @returns {string} the stringified lambda
+     * @returns {[string,string[],string]} the stringified lambda parts
      * @example
      * ```js
      * // note: these samples are actually simplified! See below.
@@ -188,21 +186,25 @@ class SourceFile extends File {
         const callableSignatures = []
         if (callStyles.positional) {
             const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}: ${type}`).join(', ') // must not include ? modifiers
-            callableSignatures.push(`// positional\n${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
+            callableSignatures.push('// positional',`${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
         }
         if (callStyles.named) {
             const parameterNames = createObjectOf(parameters.map(({name}) => normalise(name)).join(', '))
-            callableSignatures.push(`// named\n${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
+            callableSignatures.push('// named',`${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
         }
         if (callableSignatures.length === 0) throw new Error('At least one call style must be specified')
         let prefix = name ? `${normalise(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
-        const kindDef = kind ? `, kind: '${kind}'` : ''
+        const kindDef = kind ? [`kind: '${kind}'`] : []
         const suffix = initialiser ? ` = ${initialiser}` : ''
-        const lambda = `{\n${callableSignatures.join('\n')}, \n// metadata (do not use)\n__parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
-        return prefix + lambda + suffix
+
+        return [
+            `${prefix} {`,
+            [...callableSignatures, '// metadata (do not use)', `__parameters: ${parameterTypeAsObject}, __returns: ${returns}`, ...kindDef],
+            `}${suffix}`,
+        ]
     }
 
     /**
@@ -230,7 +232,8 @@ class SourceFile extends File {
     addOperation(name, parameters, returns, kind, doc, callStyles) {
         // this.operations.buffer.add(`// ${kind}`)
         if (doc) this.operations.buffer.add(doc.join('\n')) // docs shows up on action provider side: `.on(action,...)`
-        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})};`)
+        const [opener, content, closer] = SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})
+        this.operations.buffer.addIndentedBlock(`export declare const ${opener}`, content, closer)
         this.operations.names.push(name)
     }
 
@@ -397,7 +400,7 @@ class SourceFile extends File {
                 buffer.add(`import * as ${imp.asIdentifier()} from '${imp.asDirectory({relative: this.path.asDirectory()})}';`)
             }
         }
-        buffer.add('') // empty line after imports
+        buffer.blankLine()
         return buffer
     }
 
@@ -437,7 +440,7 @@ class SourceFile extends File {
         const namespace = this.path.asNamespace()
 
         const boilerplate = [AUTO_GEN_NOTE]
-        if (this.options.useEntitiesProxy) {
+        if (configuration.useEntitiesProxy) {
             if (namespace === '_') {
                 boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
             } else {
@@ -460,7 +463,7 @@ class SourceFile extends File {
      * @returns {{singularRhs: string, pluralRhs: string}}
      */
     #getEntityExportsRhs(singular, original) {
-        if (this.options.useEntitiesProxy) {
+        if (configuration.useEntitiesProxy) {
             const namespace = this.path.asNamespace()
             // determine the custom properties for the proxy function call
             const customProps = this.entityProxies[singular] ?? []
@@ -587,10 +590,27 @@ class Buffer {
 
     /**
      * Adds an element to the buffer with the current indentation level.
-     * @param {string} part  - what to attach to the buffer
+     * @param {string | (() => string) | ((() => string) | string)[]} part  - what to attach to the buffer
      */
     add(part) {
-        this.parts.push(this.currentIndent + part)
+        if (typeof part === 'string') {
+            this.parts.push(this.currentIndent + part)
+        } else if (Array.isArray(part)) {
+            for (const p of part) {
+                this.add(p)  // recurse to have proper indentation
+            }
+        } else if (typeof part === 'function') {
+            this.parts.push(part())
+        } else {
+            throw new Error(`trying to add something of type ${typeof part} to a Buffer`)
+        }
+    }
+
+    /**
+     * Adds a blank line to the buffer.
+     */
+    blankLine() {
+        this.add('')
     }
 
     /**
@@ -697,13 +717,6 @@ class FileRepository {
     /** @type {{[key:string]: SourceFile}} */
     #files = {}
 
-    /**
-     * @param {FileOptions} options - options to control file
-     */
-    constructor(options) {
-        this.options = options
-    }
-
     /**
      * @param {string} name - file name
      * @param {SourceFile} file - the file
@@ -720,7 +733,7 @@ class FileRepository {
      */
     getNamespaceFile(path) {
         const key = path instanceof Path ? path.asNamespace() : path
-        return (this.#files[key] ??= new SourceFile(path, this.options))
+        return (this.#files[key] ??= new SourceFile(path))
     }
 
     /**