@cap-js/cds-typer 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -4,7 +4,20 @@ 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.28.0 - TBD
+## Version 0.29.0 - TBD
+
+## Version 0.28.0 - 24-10-24
+### Added
+- Schema definition for `cds.typer` options in `package.json` and `.cdsrc-*.json` files
+- Added a static `elements` property to all entities, which allows access to the `LinkedDefinitions` instance of an entity's elements
+- Schema definition for `typescript` cds build task.
+- `.drafts` property of any entity `E` is now of type `DraftOf<E>`, or `DraftsOf<E>` for plurals, respectively. This type exposes dditional properties that are available on drafts during runtime.
+
+### Fixed
+- Entity elements of named structured types are flattened when using the option `--inlineDeclarations flat`
+- `override` modifier on `.kind` property is now only generated if the property is actually inherited, satisfying strict `tsconfig.json`s
+- Properly support mandatory (`not null`) action parameters with `array of` types
+- Static property `.drafts` is only create for entity classes that are actually draft enabled
 
 ## Version 0.27.0 - 2024-10-02
 ### Changed
@@ -13,7 +26,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Fixed
 - Fix build task for projects with spaces
-- Fixa bug where cds-typer would produce redundant type declarations when the model contains an associations to another entity's property
+- Fix a bug where cds-typer would produce redundant type declarations when the model contains an associations to another entity's property
+- Reintroduce default value `'.'` for `--outputDirectory`
 
 ## Version 0.26.0 - 2024-09-11
 ### Added

package/lib/components/basedefs.js

@@ -13,6 +13,10 @@ const timeRegex = '`${number}${number}:${number}${number}:${number}${number}`'
 const baseDefinitions = new SourceFile('_')
 // FIXME: this should be a library someday
 baseDefinitions.addPreamble(`
+import { type } from '@sap/cds'
+
+export type ElementsOf<T> = {[name in keyof Required<T>]: type }
+
 export namespace Association {
     export type to <T> = T;
     export namespace to {
@@ -38,6 +42,16 @@ export type EntitySet<T> = T[] & {
     data (input:object) : T
 };
 
+export type DraftEntity<T> = T & {
+    IsActiveEntity?: boolean | null
+    HasActiveEntity?: boolean | null
+    HasDraftEntity?: boolean | null
+    DraftAdministrativeData_DraftUUID?: string | null
+}
+
+export type DraftOf<T> = { new(...args: any[]): DraftEntity<T> }
+export type DraftsOf<T> = typeof Array<DraftEntity<T>>
+
 export type DeepRequired<T> = { 
     [K in keyof T]: DeepRequired<T[K]>
 } & Exclude<Required<T>, null>;

package/lib/components/class.js

@@ -0,0 +1,35 @@
+/**
+ * Create a class member with given modifiers in the right order.
+ * @param {object} options - options
+ * @param {string} options.name - the name of the member
+ * @param {string} [options.type] - the type of the member
+ * @param {string} [options.initialiser] - the initialiser for the member
+ * @param {string} [options.statementEnd] - the closing character for the member
+ * @param {boolean} [options.isDeclare] - whether the member is declared
+ * @param {boolean} [options.isStatic] - whether the member is static
+ * @param {boolean} [options.isReadonly] - whether the member is readonly
+ * @param {boolean} [options.isOverride] - whether the member is an override
+ */
+function createMember ({name, type = undefined, initialiser = undefined, statementEnd = ';', isDeclare = false,  isStatic = false, isReadonly = false, isOverride = false}) {
+    if (isDeclare && isOverride) throw new Error('member cannot have both declare and override modifiers')
+
+    const parts = []
+
+    if (isDeclare) parts.push('declare')
+    if (isStatic) parts.push('static')
+    if (isOverride) parts.push('override')
+    if (isReadonly) parts.push('readonly')
+
+    parts.push(type ? `${name}: ${type}` : name)
+
+    if (initialiser) parts.push(`= ${initialiser}`)
+
+    const member = parts.join(' ')
+    return statementEnd
+        ? `${member}${statementEnd}`
+        : member
+}
+
+module.exports = {
+    createMember
+}

package/lib/components/enum.js

@@ -55,12 +55,12 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
 function printEnum(buffer, name, kvs, options = {}, doc=[]) {
     const opts = {...{export: true}, ...options}
     buffer.add('// enum')
-    if (opts.export) doc.forEach(d => { buffer.add(d) })
+    if (opts.export) buffer.add(doc)
     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('')
+    buffer.blankLine()
 }
 
 /**

package/lib/components/inline.js

@@ -4,6 +4,7 @@ const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
 
 /** @typedef {import('../resolution/resolver').TypeResolveInfo} TypeResolveInfo */
+/** @typedef {import('../resolution/resolver').TypeResolveOptions} TypeResolverOptions */
 /** @typedef {import('../typedefs').visitor.Inflection} Inflection */
 /** @typedef {import('../typedefs').resolver.PropertyModifier} PropertyModifier */
 /** @typedef {import('../visitor').Visitor} Visitor */
@@ -34,9 +35,10 @@ class InlineDeclarationResolver {
      * @param {any} items - properties of the declaration we are resolving
      * @param {TypeResolveInfo} into - @see Visitor.resolveType
      * @param {SourceFile} relativeTo - file to which the resolved type should be relative to
+     * @param {TypeResolverOptions} [options] - resolver options
      * @public
      */
-    resolveInlineDeclaration(items, into, relativeTo) {
+    resolveInlineDeclaration(items, into, relativeTo, options) {
         const dummy = new SourceFile(relativeTo.path.asDirectory())
         dummy.classes.currentIndent = relativeTo.classes.currentIndent
         dummy.classes.add('{')
@@ -51,7 +53,9 @@ class InlineDeclarationResolver {
             const se = (typeof subelement === 'string')
                 ? this.visitor.resolver.resolveTypeName(subelement)
                 : subelement
-            into.structuredType[subname] = this.visitor.visitElement(subname, se, dummy)
+            // resolver options need to be passed through, otherwise deep expand of struct types to flat
+            // does not work
+            into.structuredType[subname] = this.visitor.visitElement({name: subname, element: se, file: dummy, resolverOptions: options})
         }
         dummy.classes.outdent()
         dummy.classes.add('}')
@@ -73,14 +77,15 @@ class InlineDeclarationResolver {
      * @param {SourceFile} options.file - the namespace file the surrounding entity is being printed into.
      * @param {Buffer} options.buffer - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
      * @param {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
+     * @param {TypeResolverOptions} [options.resolverOptions] - resolver options
      * @public
      */
-    visitElement({name, element, file, buffer = file.classes, modifiers = []}) {
+    visitElement({name, element, file, buffer = file.classes, modifiers = [], resolverOptions}) {
         this.depth++
         for (const d of docify(element.doc)) {
             buffer.add(d)
         }
-        const type = this.visitor.resolver.resolveAndRequire(element, file)
+        const type = this.visitor.resolver.resolveAndRequire(element, file, resolverOptions)
         this.depth--
         if (this.depth === 0) {
             this.printInlineType({fq: name, type, buffer, modifiers})
@@ -106,7 +111,8 @@ class InlineDeclarationResolver {
      * @public
      */
     getPropertyDatatype(type, typeName = type.typeName) {
-        return type.typeInfo.isNotNull ? typeName : `${typeName} | null`
+        // do not append null if already added to type
+        return type.typeInfo.isNotNull ? typeName : typeName.endsWith('| null') ? typeName : `${typeName} | null`
     }
 
     /**
@@ -268,10 +274,9 @@ class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
      * @type {InlineDeclarationResolver['printInlineType']}
      */
     printInlineType({fq, type, buffer, modifiers, statementEnd}) {
-        // FIXME: indent not quite right
         const sub = new Buffer()
-        sub.currentIndent = buffer.currentIndent
-        buffer.add(this.flatten({fq, type, buffer: sub, modifiers, statementEnd}).join())
+        this.flatten({fq, type, buffer: sub, modifiers, statementEnd})
+        buffer.add(sub.parts)
     }
 
     /**

package/lib/components/wrappers.js

@@ -17,6 +17,27 @@ const createKey = t => `${base}.Key<${t}>`
  */
 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.
@@ -98,10 +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,
@@ -110,5 +141,6 @@ module.exports = {
     createCompositionOfOne,
     createCompositionOfMany,
     deepRequire,
-    docify
+    docify,
+    stringIdent
 }

package/lib/config.js

@@ -34,7 +34,8 @@ class Config {
     static #defaults = {
         propertiesOptional: true,
         useEntitiesProxy: false,
-        inlineDeclarations: 'flat'
+        inlineDeclarations: 'flat',
+        outputDirectory: '.'
     }
 
     values = undefined

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

@@ -157,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.
@@ -186,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}`,
+        ]
     }
 
     /**
@@ -228,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)
     }
 
@@ -395,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
     }
 
@@ -585,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('')
     }
 
     /**

package/lib/resolution/entity.js

@@ -61,6 +61,7 @@ class EntityInfo {
     /** @type {import('../typedefs').resolver.EntityCSN | undefined} */
     #csn
 
+    /** @returns the **inferred** csn for this entity. */
     get csn () {
         return this.#csn ??= this.#resolver.csn.definitions[this.fullyQualifiedName]
     }

package/lib/resolution/resolver.js

@@ -19,6 +19,7 @@ const { configuration } = require('../config')
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
 /** @typedef {import('../typedefs').resolver.EntityCSN} EntityCSN */
 /** @typedef {import('../typedefs').resolver.TypeResolveInfo} TypeResolveInfo */
+/** @typedef {import('../typedefs').resolver.TypeResolveOptions} TypeResolveOptions */
 /** @typedef {import('../typedefs').visitor.Inflection} Inflection */
 /** @typedef {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection }}} ResolveAndRequireInfo */
 
@@ -64,7 +65,7 @@ class Resolver {
      * @returns {boolean} whether the type is configured to be optional
      */
     isOptional(type) {
-        return !type.notNull
+        return type.items ? !type.items.notNull : !type.notNull
     }
 
     /**
@@ -233,7 +234,7 @@ class Resolver {
                 statementEnd: '',
                 modifiers: getPropertyModifiers(typeInfo.csn)
             })
-            typeName = into.join(' ')
+            typeName = into.join()
             singular = typeName
             plural = createArrayOf(typeName)
         } else {
@@ -276,10 +277,11 @@ class Resolver {
      * 3. return a properly prefixed name to use within model2.d.ts, e.g. "m1.Foo"
      * @param {import('../visitor').EntityCSN} element - the CSN element to resolve the type for.
      * @param {SourceFile} file - source file for context.
+     * @param {TypeResolveOptions} [options] - resolver options
      * @returns {ResolveAndRequireInfo} info about the resolved type
      */
-    resolveAndRequire(element, file) {
-        const typeInfo = this.resolveType(element, file)
+    resolveAndRequire(element, file, options) {
+        const typeInfo = this.resolveType(element, file, options)
         const cardinality = getMaxCardinality(element)
 
         let typeName = typeInfo.plainName ?? typeInfo.type
@@ -434,9 +436,10 @@ class Resolver {
      * Enriched with additional information for improved printout (see return type).
      * @param {import('../typedefs').resolver.EntityCSN | TypeResolveInfo} element - the CSN element to resolve the type for.
      * @param {SourceFile} file - source file for context.
+     * @param {TypeResolveOptions} [options] - resolver options
      * @returns {TypeResolveInfo} description of the resolved type
      */
-    resolveType(element, file) {
+    resolveType(element, file, options) {
         // while resolving inline declarations, it can happen that we land here
         // with an already resolved type. In that case, just return the type we have.
         // type guard check purely to satisfy return statement
@@ -505,9 +508,10 @@ class Resolver {
             result.isBuiltin = true
             this.resolveType(element.items, file)
             //delete element.items
-        } else if (element?.elements && !element?.type) {
+        } else if (element?.elements && (options?.forceInlineStructs || !element?.type)) {
             // explicitly skip named type definitions, which have elements too, but should not be considered inline declarations
-            this.#resolveInlineDeclarationType(element.elements, result, file)
+            // if the resolver option `forceInlineStructs` is `true`, named types in elements will be converted to inline
+            this.#resolveInlineDeclarationType(element.elements, result, file, options)
         }
 
         if (result.isBuiltin === false && result.isInlineDeclaration === false && !result.plainName) {
@@ -529,11 +533,12 @@ class Resolver {
      * @param {{ [key: string]: EntityCSN }} items - the properties of the inline declaration.
      * @param {TypeResolveInfo} into - @see resolveType()
      * @param {SourceFile} relativeTo - the sourcefile in which we have found the reference to the type.
+     * @param {TypeResolveOptions} [options] - resolver options
      *  This is important to correctly detect when a field in the inline declaration is referencing
      *  types from the CWD. In that case, we will not add an import for that type and not add a namespace-prefix.
      */
-    #resolveInlineDeclarationType(items, into, relativeTo) {
-        return this.visitor.inlineDeclarationResolver.resolveInlineDeclaration(items, into, relativeTo)
+    #resolveInlineDeclarationType(items, into, relativeTo, options) {
+        return this.visitor.inlineDeclarationResolver.resolveInlineDeclaration(items, into, relativeTo, options)
     }
 
     /**

package/lib/typedefs.d.ts

@@ -82,6 +82,39 @@ export module resolver {
         inflection?: visitor.Inflection
     }
 
+    /**
+     * Custom options to be used during type resolvement
+     */
+    export type TypeResolveOptions = {
+        /**
+         * Entity elements that have a custom type are not available when entity is accessed using CQL.
+         *
+         * They only exist in the original defined form in the CSN and LinkedCSN but not in the compiled
+         * OData or SQL models (i.e. `cds.compile(..).for.odata()`).
+         * 
+         * Therefore they need to be flattened down like inline structs.
+         * 
+         * ```cds
+         * // model.cds
+         * type Adress {
+         *   street: String;
+         *   zipCode: String;
+         * }
+         * entity Persons {
+         *   title: String
+         *   address: Adress
+         * }
+         * ```
+         * 
+         * // service.js
+         * ```js
+         * const {title, address_street, address_zipCode} = await SELECT.from(Persons);
+         * ```
+         * 
+         */
+        forceInlineStructs?: boolean
+    }
+
     export type EntityInfo = Exclude<ReturnType<import('../lib/resolution/entity').EntityRepository['getByFq']>, null>
 
     // TODO: this will be completely replaced by EntityInfo

package/lib/visitor.js

@@ -2,13 +2,13 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, isType, isProjection, getMaxCardinality, isViewOrProjection, isEnum } = require('./csn')
+const { isView, isUnresolved, propagateForeignKeys, collectDraftEnabledEntities, isDraftEnabled, isType, isProjection, getMaxCardinality, isViewOrProjection, isEnum, isEntity } = require('./csn')
 // eslint-disable-next-line no-unused-vars
 const { SourceFile, FileRepository, Buffer, Path } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./resolution/resolver')
 const { LOG } = require('./logging')
-const { docify, createPromiseOf, createUnionOf, createKeysOf } = require('./components/wrappers')
+const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
@@ -17,11 +17,13 @@ const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
 const { configuration } = require('./config')
+const { createMember } = require('./components/class')
 
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
 /** @typedef {import('./typedefs').resolver.CSN} CSN */
+/** @typedef {import('./typedefs').resolver.TypeResolveOptions} TypeResolveOptions */
 /** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
 /** @typedef {import('./typedefs').resolver.EnumCSN} EnumCSN */
 
@@ -40,8 +42,10 @@ class Visitor {
      * @param {{xtended: CSN, inferred: CSN}} csn - root CSN
      */
     constructor(csn) {
-        amendCSN(csn.xtended)
+        propagateForeignKeys(csn.xtended)
         propagateForeignKeys(csn.inferred)
+        // has to be executed on the inferred model as autoexposed entities are not included in the xtended csn
+        collectDraftEnabledEntities(csn.inferred)
         this.csn = csn
 
         /** @type {Context[]} **/
@@ -139,18 +143,27 @@ class Visitor {
             : ''
         if (actions.length) {
             buffer.addIndentedBlock(`declare static readonly actions: ${inherited}{`,
-                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',
-                    kind: action.kind,
-                    doc: docify(action.doc)
-                })), '}'
+                () => {
+                    for (const [aname, action] of actions) {
+                        const [opener, content, closer] = SourceFile.stringifyLambda({
+                            name: aname,
+                            parameters: this.#stringifyFunctionParams(action.params, file),
+                            returns: action.returns
+                                ? this.resolver.resolveAndRequire(action.returns, file).typeName
+                                : 'any',
+                            kind: action.kind,
+                            doc: docify(action.doc)})
+                        buffer.addIndentedBlock(opener, content, closer)
+                    }
+                }, '}'
             ) // end of actions
         } else {
-            buffer.add(`declare static readonly actions: ${inherited}${empty}`)
+            buffer.add(createMember({
+                name: 'actions',
+                type: `${inherited}${empty}`,
+                isStatic: true,
+                isReadonly: true
+            }))
         }
     }
 
@@ -159,7 +172,27 @@ class Visitor {
      * @param {string} clean - the clean name of the entity
      */
     #printStaticKeys(buffer, clean) {
-        buffer.add(`declare static readonly keys: ${createKeysOf(clean)}`)
+        buffer.add(createMember({
+            name: 'keys',
+            type: createKeysOf(clean),
+            isDeclare: true,
+            isStatic: true,
+            isReadonly: true,
+        }))
+    }
+
+    /**
+     * @param {Buffer} buffer - the buffer to write the elements into
+     * @param {string} clean - the clean name of the entity
+     */
+    #printStaticElements(buffer, clean) {
+        buffer.add(createMember({
+            name: 'elements',
+            type: createElementsOf(clean),
+            isDeclare: true,
+            isStatic: true,
+            isReadonly: true
+        }))
     }
 
     /**
@@ -229,12 +262,15 @@ class Visitor {
             buffer.addIndentedBlock(`return class ${clean} extends ${ancestorsAspects} {`, () => {
                 /** @type {import('./typedefs').resolver.EnumCSN[]} */
                 const enums = []
-                for (let [ename, element] of Object.entries(entity.elements ?? {})) {
+                /** @type {TypeResolveOptions} */
+                const resolverOptions = { forceInlineStructs: isEntity(entity) && configuration.inlineDeclarations === 'flat'}
+
+                for (let [ename, element] of Object.entries(entity.elements ?? [])) {
                     if (element.target && /\.texts?/.test(element.target)) {
                         LOG.warn(`referring to .texts property in ${fq}. This is currently not supported and will be ignored.`)
                         continue
                     }
-                    this.visitElement(ename, element, file, buffer)
+                    this.visitElement({name: ename, element, file, buffer, resolverOptions})
 
                     // make foreign keys explicit
                     if (element.target) {
@@ -250,7 +286,7 @@ class Visitor {
                                     const kelement = Object.assign(Object.create(originalKeyElement), {
                                         isRefNotNull: !!element.notNull || !!element.key
                                     })
-                                    this.visitElement(foreignKey, kelement, file, buffer)
+                                    this.visitElement({name: foreignKey, element: kelement, file, buffer, resolverOptions})
                                 }
                             }
                         }
@@ -262,37 +298,49 @@ class Visitor {
                     }
                 }
 
-                if ('kind' in entity) {
-                    buffer.addIndented([`static readonly kind: 'entity' | 'type' | 'aspect' = '${entity.kind}';`])
+                for (const e of enums) {
+                    const eDoc = docify(e.doc)
+                    buffer.add(eDoc)
+                    buffer.add(createMember({
+                        name: e.name,
+                        initialiser: propertyToInlineEnumName(clean, e.name),
+                        isStatic: true,
+                    }))
+                    file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
                 }
 
-                buffer.addIndented(() => {
-                    for (const e of enums) {
-                        const eDoc = docify(e.doc)
-                        eDoc.forEach(d => { buffer.add(d) })
-                        buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
-                        file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
-                    }
-                    this.#printStaticActions(entity, buffer, ancestorInfos, file)
-                    this.#printStaticKeys(buffer, clean)
-
-                })
+                if ('kind' in entity) {
+                    buffer.add(createMember({
+                        name: 'kind',
+                        type: '"entity" | "type" | "aspect"',
+                        isStatic: true,
+                        isReadonly: true,
+                        isDeclare: false,
+                        isOverride: ancestorInfos.some(ancestor => ancestor.csn.kind),
+                        initialiser: stringIdent(entity.kind)
+                    }))
+                }
+                this.#printStaticKeys(buffer, clean)
+                this.#printStaticElements(buffer, clean)
+                this.#printStaticActions(entity, buffer, ancestorInfos, file)
             }, '};') // end of generated class
         }, '}') // end of aspect
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
         docify(entity.doc).forEach(d => { buffer.add(d) })
-        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(clean, entity).join('\n')}}`)
+        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(fq, clean).join('\n')}}`)
         this.contexts.pop()
     }
 
     /**
+     * @param {string} fq - fully qualified name of the entity
      * @param {string} clean - the clean name of the entity
-     * @param {EntityCSN} entity - the entity to generate the static contents for
+     * @param {boolean} [isPlural] - `true` if passed entity is plural
      */
-    #staticClassContents(clean, entity) {
-        return isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : []
+    #staticClassContents(fq, clean, isPlural = false) {
+        if (!isDraftEnabled(fq)) return []
+        return [`static drafts: ${isPlural ? createDraftsOf(clean) : createDraftOf(clean)}`]
     }
 
     /**
@@ -348,9 +396,6 @@ class Visitor {
             ? this.csn.inferred.definitions[fq]
             : entity
 
-        // draft enablement is stored in csn.xtended. Iff we took the entity from csn.inferred, we have to carry the draft-enablement over at this point
-        target['@odata.draft.enabled'] = isDraftEnabled(entity)
-
         this.#aspectify(fq, target, buffer, { cleanName: singular })
 
         buffer.add(overrideNameProperty(singular, entity.name))
@@ -366,13 +411,13 @@ 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.
-            const additionalProperties = this.#staticClassContents(singular, entity)
+            const additionalProperties = this.#staticClassContents(fq, singular, true)
             additionalProperties.push('$count?: number')
-            docify(entity.doc).forEach(d => { buffer.add(d) })
+            buffer.add(docify(entity.doc))
             buffer.add(`export class ${plural} extends Array<${singular}> {${additionalProperties.join('\n')}}`)
             buffer.add(overrideNameProperty(plural, entity.name))
         }
-        buffer.add('')
+        buffer.blankLine()
     }
 
     /**
@@ -496,7 +541,7 @@ class Visitor {
             // FIXME: shouldn't need to change config here! Idea: init Visitor with .options fed from config, then manipulate that
             configuration.propertiesOptional = false
             for (const [ename, element] of Object.entries(event.elements ?? {})) {
-                this.visitElement(ename, element, file, buffer)
+                this.visitElement({name: ename, element, file, buffer})
             }
             configuration.propertiesOptional = propOpt
         }, '}')
@@ -517,12 +562,12 @@ class Visitor {
         // file.addImport(new Path(['cds'], '')) TODO make sap/cds import work
         buffer.addIndentedBlock(`export class ${serviceNameSimple} extends cds.Service {`, () => {
             Object.entries(service.operations ?? {}).forEach(([name, {doc}]) => {
-                docify(doc).forEach(d => { buffer.add(d) })
+                buffer.add(docify(doc))
                 buffer.add(`declare ${name}: typeof ${name}`)
             })
         }, '}')
         buffer.add(`export default ${serviceNameSimple}`)
-        buffer.add('')
+        buffer.blankLine()
         file.addService(service.name)
     }
 
@@ -585,13 +630,15 @@ class Visitor {
 
     /**
      * Visits a single element in an entity.
-     * @param {string} name - name of the element
-     * @param {EntityCSN} 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.
+     * @param {object} options - options
+     * @param {string} options.name - name of the element
+     * @param {EntityCSN} options.element - CSN data belonging to the the element.
+     * @param {SourceFile} options.file - the namespace file the surrounding entity is being printed into.
+     * @param {Buffer} [options.buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @param {TypeResolveOptions} [options.resolverOptions] - custom type resolver options
      * @returns @see InlineDeclarationResolver.visitElement
      */
-    visitElement(name, element, file, buffer = file.classes) {
+    visitElement({name, element, file, buffer = file.classes, resolverOptions}) {
         return this.inlineDeclarationResolver.visitElement({
             name,
             element,
@@ -599,7 +646,8 @@ class Visitor {
             buffer,
             // we explicitly pass the "declare" modifier here to avoid problems with noImplicitOverride and useDefineForClassFields in strict tsconfigs
             // but not inside type defs (e.g. parameter types) where this would be a syntax error
-            modifiers: getPropertyModifiers(element)
+            modifiers: getPropertyModifiers(element),
+            resolverOptions
         })
     }
 }

package/library/cds.hana.ts

@@ -9,7 +9,7 @@ export class VARCHAR extends String {};
 export class CLOB extends String {};
 export class BINARY extends String {}
 export class ST_POINT {
-    public x: number;
-    public y: number;
+    declare public x: number;
+    declare public y: number;
 }
 export class ST_GEOMETRY { /* FIXME */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.27.0",
+  "version": "0.28.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",
@@ -25,7 +25,8 @@
     "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:cli": "npm run cli -- --help > ./doc/cli.txt",
-    "jsdoc:check": "tsc --noEmit --project jsconfig.json"
+    "jsdoc:check": "tsc --noEmit --project jsconfig.json",
+    "write:cds-typer-shema": "node scripts/write-cds-typer-schema.js"
   },
   "files": [
     "lib/",
@@ -60,5 +61,72 @@
       "test/smoke.jest.config.js",
       "test/unit.jest.config.js"
     ]
+  },
+  "cds": {
+    "schema": {
+      "buildTaskType": {
+        "name": "typescript",
+        "description": "TypeScript build plugin. For use after the nodejs build task."
+      },
+      "cds": {
+        "typer": {
+          "type": "object",
+          "description": "Configuration for CDS Typer",
+          "properties": {
+            "output_directory": {
+              "type": "string",
+              "description": "Root directory to write the generated files to.",
+              "default": "@cds-models"
+            },
+            "log_level": {
+              "type": "string",
+              "description": "Minimum log level that is printed.\nThe default is only used if no explicit value is passed\nand there is no configuration passed via cds.env either.",
+              "enum": [
+                "SILENT",
+                "ERROR",
+                "WARN",
+                "INFO",
+                "DEBUG",
+                "TRACE",
+                "SILLY",
+                "VERBOSE",
+                "WARNING",
+                "CRITICAL",
+                "NONE"
+              ],
+              "default": "ERROR"
+            },
+            "js_config_path": {
+              "type": "string",
+              "description": "Path to where the jsconfig.json should be written.\nIf specified, cds-typer will create a jsconfig.json file and\nset it up to restrict property usage in types entities to\nexisting properties only."
+            },
+            "use_entities_proxy": {
+              "type": "boolean",
+              "description": "If set to true the 'cds.entities' exports in the generated 'index.js'\nfiles will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.\n\nWARNING: entity properties can still only be accessed after\n'cds.entities' has been loaded",
+              "default": false
+            },
+            "inline_declarations": {
+              "type": "string",
+              "description": "Whether to resolve inline type declarations\nflat: (x_a, x_b, ...)\nor structured: (x: {a, b}).",
+              "enum": [
+                "flat",
+                "structured"
+              ],
+              "default": "structured"
+            },
+            "properties_optional": {
+              "type": "boolean",
+              "description": "If set to true, properties in entities are\nalways generated as optional (a?: T).",
+              "default": true
+            },
+            "ieee754compatible": {
+              "type": "boolean",
+              "description": "If set to true, floating point properties are generated\nas IEEE754 compatible '(number | string)' instead of 'number'.",
+              "default": false
+            }
+          }
+        }
+      }
+    }
   }
 }