@cap-js/cds-typer 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -4,7 +4,31 @@ 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.25.0 - TBD
+## Version 0.27.0 - TBD
+
+## Version 0.26.0 - 2024-09-11
+### Added
+- Added a CLI option `--useEntitiesProxy`. When set to `true`, all entities are wrapped into `Proxy` objects during runtime, allowing top level imports of entity types.
+- Added a static `.kind` property for entities and types, which contains `'entity'` or `'type'` respectively
+- Apps need to provide `@sap/cds` version `8.2` or higher.
+- Apps need to provide `@cap-js/cds-types` version `0.6.4` or higher.
+- Typed methods are now generated for calls of unbound actions. Named and positional call styles are supported, e.g. `service.action({one, two})` and `service.action(one, two)`.
+- Action parameters can be optional in the named call style (`service.action({one:1, ...})`).
+- Actions for ABAP RFC modules cannot be called with positional parameters, but only with named ones. They have 'parameter categories' (import/export/changing/tables) that cannot be called in a flat order.
+- Services now have their own export (named like the service itself). The current default export is not usable in some scenarios from CommonJS modules.
+- Enums and operation parameters can have doc comments
+
+
+## Version 0.25.0 - 2024-08-13
+### Added
+- Declaring a type alias on an enum in cds now also exports it on value level in the resulting type
+
+### Fixed
+- Classes representing views and projections will no longer carry ancestry to avoid clashes thereof with aliases fields
+
+### Changed
+- All properties are now preceeded with the `declare` modifier to pass strict tsconfigs using `useDefineForClassFields` or `noImplicitOverride`
+- The static `actions` property of generated classes now includes the types from all inherited classes to also suggest actions defined in a base entity/aspect/type.
 
 ## Version 0.24.0 - 2024-07-18
 ### Fixed
@@ -16,10 +40,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - The TypeScript task for `cds build` no longer looks for tsconfig.json to determine if the project has TS nature and instead checks the dependencies in the project's package.json for an occurrence of `typescript`
 
 ## Version 0.23.0 - 2024-07-04
+
 ### Fixed
 - Plurals no longer have `is_singular` attached in the resulting .js files
 - Properties are properly propagated beyond just one level of inheritance
 
+
 ## Version 0.22.0 - 2024-06-20
 ### Fixed
 - Fixed a bug where keys would sometimes inconsistently become nullable
@@ -72,7 +98,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Importing an enum into a service will now generate an alias to the original enum, instead of incorrectly duplicating the definition
 - Returning entities from actions/ functions and using them as parameters will now properly use the singular inflection instead of returning an array thereof
 - Aspects are now consistently named and called in their singular form
-- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation 
+- Only detect inflection clash if singular and plural share the same namespace. This also no longer reports `sap.common` as erroneous during type creation
 
 ## Version 0.19.0 - 2024-03-28
 ### Added

package/README.md

@@ -9,6 +9,25 @@ Generates `.ts` files for a CDS model to receive code completion in VS Code.
 
 Exhaustive documentation can be found on [CAPire](https://cap.cloud.sap/docs/tools/cds-typer).
 
+## Known Restrictions
+
+Certain language features of CDS can not be represented in TypeScript.
+Trying to generate types for models using these features will therefore result in incorrect or broken TypeScript code.
+
+### Changing Types
+
+While the following is valid CDS, there is no TypeScript equivalent that would allow the type of an inherited property to change (TS2416).
+
+```cds
+entity A {
+  foo: Integer
+};
+
+entity B: A {
+  foo: String
+}
+```
+
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/cds-typer/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).

package/lib/cli.js

@@ -12,6 +12,9 @@ const { EOL } = require('node:os')
 const EOL2 = EOL + EOL
 const toolName = 'cds-typer'
 
+// @ts-expect-error - nope, it is actually there. Types just seem to be out of sync.
+const lls = cds.log.levels
+
 const flags = {
     outputDirectory: {
         desc: 'Root directory to write the generated files to.',
@@ -23,15 +26,20 @@ const flags = {
     },
     logLevel: {
         desc: `Minimum log level that is printed.${EOL}The default is only used if no explicit value is passed${EOL}and there is no configuration passed via cds.env either.`,
-        allowed: Object.keys(cds.log.levels).concat(Object.keys(deprecated)),
-        allowedHint: Object.keys(cds.log.levels).join(' | '),  // FIXME: remove once old levels are faded out
-        defaultHint: _keyFor(cds.log.levels.ERROR),
-        default: cds?.env?.log?.levels?.['cds-typer'] ?? _keyFor(cds.log.levels.ERROR),
+        allowed: Object.keys(lls).concat(Object.keys(deprecated)),
+        allowedHint: Object.keys(lls).join(' | '),  // FIXME: remove once old levels are faded out
+        defaultHint: _keyFor(lls.ERROR),
+        default: cds?.env?.log?.levels?.['cds-typer'] ?? _keyFor(lls.ERROR),
     },
     jsConfigPath: {
         desc: `Path to where the jsconfig.json should be written.${EOL}If specified, ${toolName} will create a jsconfig.json file and${EOL}set it up to restrict property usage in types entities to${EOL}existing properties only.`,
         type: 'string'
     },
+    useEntitiesProxy: {
+        desc: `If set to true the 'cds.entities' exports in the generated 'index.js'${EOL}files will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.${EOL}${EOL}WARNING: entity properties can still only be accessed after${EOL}'cds.entities' has been loaded`,
+        allowed: ['true', 'false'],
+        default: 'false'
+    },
     version: {
         desc: 'Prints the version of this tool.'
     },
@@ -53,25 +61,32 @@ const flags = {
 }
 
 const hint = () => 'Missing or invalid parameter(s). Call with --help for more details.'
-const indent = (s, indentation) => s.split(EOL).map(line => `${indentation}${line}`).join(EOL)
+/**
+ * @param {string} s - the string to indent
+ * @param {string} indentation - the indentation to use
+ */
+const indent = (s, indentation) => s
+    .split(EOL)
+    .map((/** @type {string} */ line) => `${indentation}${line}`)
+    .join(EOL)
 
 const help = () => `SYNOPSIS${EOL2}` +
         indent('cds-typer [cds file | "*"]', '  ') + EOL2 +
         indent(`Generates type information based on a CDS model.${EOL}Call with at least one positional parameter pointing${EOL}to the (root) CDS file you want to compile.`, '  ') + EOL2 +
             `OPTIONS${EOL2}` +
             Object.entries(flags)
-                .sort()
+                .sort(([a], [b]) => a.localeCompare(b))
                 .map(([key, value]) => {
                     let s = indent(`--${key}`, '  ')
-                    if (value.allowedHint) {
-                        s += ` ${value.allowedHint}`
-                    } else if (value.allowed) {
-                        s += `: <${value.allowed.join(' | ')}>`
-                    } else if (value.type) {
-                        s += `: <${value.type}>`
-                    }
+                    // @ts-expect-error - not going to check presence of each property. Same for the following expect-errors.
+                    if (value.allowedHint) s += ` ${value.allowedHint}`
+                    // @ts-expect-error
+                    else if (value.allowed) s += `: <${value.allowed.join(' | ')}>`
+                    else if ('type' in value && value.type) s += `: <${value.type}>`
+                    // @ts-expect-error
                     if (value.defaultHint || value.default) {
                         s += EOL
+                        // @ts-expect-error
                         s += indent(`(default: ${value.defaultHint ?? value.default})`, '    ')
                     }
                     s += `${EOL2}${indent(value.desc, '    ')}`
@@ -81,7 +96,7 @@ const help = () => `SYNOPSIS${EOL2}` +
 
 const version = () => require('../package.json').version
 
-const main = async args => {
+const main = async (/** @type {any} */ args) => {
     if ('help' in args.named) {
         console.log(help())
         process.exit(0)
@@ -107,6 +122,7 @@ const main = async args => {
         // temporary fix until rootDir is faded out
         outputDirectory: [args.named.outputDirectory, args.named.rootDir].find(d => d !== './') ?? './',
         logLevel: args.named.logLevel,
+        useEntitiesProxy: args.named.useEntitiesProxy === 'true',
         jsConfigPath: args.named.jsConfigPath,
         inlineDeclarations: args.named.inlineDeclarations,
         propertiesOptional: args.named.propertiesOptional === 'true',

package/lib/compile.js

@@ -26,7 +26,7 @@ const writeJsConfig = path => {
     }
 
     if (fs.existsSync(path)) {
-        const currentContents = JSON.parse(fs.readFileSync(path))
+        const currentContents = JSON.parse(fs.readFileSync(path, 'utf8'))
         if (currentContents?.compilerOptions?.checkJs) {
             LOG.warn(`jsconfig at location ${path} already exists. Attempting to merge.`)
         }
@@ -39,7 +39,7 @@ const writeJsConfig = path => {
 
 /**
  * Compiles a CSN object to Typescript types.
- * @param {{xtended: CSN, inferred: CSN}} csn - csn tuple
+ * @param {{xtended: import('./typedefs').resolver.CSN, inferred: import('./typedefs').resolver.CSN}} csn - csn tuple
  * @param {CompileParameters} parameters - path to root directory for all generated files, min log level
  */
 const compileFromCSN = async (csn, parameters) => {
@@ -57,7 +57,7 @@ const compileFromCSN = async (csn, parameters) => {
 
 /**
  * Compiles a .cds file to Typescript types.
- * @param {string} inputFile - path to input .cds file
+ * @param {string | string[]} inputFile - path to input .cds file
  * @param {CompileParameters} parameters - path to root directory for all generated files, min log level, etc.
  */
 const compileFromFile = async (inputFile, parameters) => {

package/lib/components/enum.js

@@ -19,6 +19,11 @@ const uniqueValues = kvs => new Set(kvs.map(([,v]) => v?.val ?? v))  // in case
 const stringifyEnumType = kvs => [...uniqueValues(kvs)].join(' | ')
 
 // in case of strings, wrap in quotes and fallback to key to make sure values are attached for every key
+/**
+ * @param {string} key - the key of the enum
+ * @param {any} value - the value of the enum
+ * @param {string | import('../typedefs').resolver.ref} enumType - the type of the enum
+ */
 const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.stringify(`${value ?? key}`) : value
 
 /**
@@ -41,14 +46,16 @@ const enumVal = (key, value, enumType) => enumType === 'cds.String' ? JSON.strin
  * const E = { a: 'A', b: 'B' }
  * type E = 'A' | 'B'
  * ```
- * @param {Buffer} buffer - Buffer to write into
+ * @param {import('../file').Buffer} buffer - Buffer to write into
  * @param {string} name - local name of the enum, i.e. the name under which it should be created in the .ts file
  * @param {[string, string][]} kvs - list of key-value pairs
  * @param {object} options - options for printing the enum
+ * @param {string[]} doc - the enum docs
  */
-function printEnum(buffer, name, kvs, options = {}) {
+function printEnum(buffer, name, kvs, options = {}, doc=[]) {
     const opts = {...{export: true}, ...options}
     buffer.add('// enum')
+    if (opts.export) doc.forEach(d => { buffer.add(d) })
     buffer.addIndentedBlock(`${opts.export ? 'export ' : ''}const ${name} = {`, () =>
         kvs.forEach(([k, v]) => { buffer.add(`${normalise(k)}: ${v},`) })
     , '} as const;')
@@ -60,12 +67,13 @@ function printEnum(buffer, name, kvs, options = {}) {
  * Converts a CSN type describing an enum into a list of kv-pairs.
  * Values from CSN are unwrapped from their `.val` structure and
  * will fall back to the key if no value is provided.
- * @param {{enum: {[key: name]: string}, type: string}} enumCsn - the CSN type describing the enum
- * @param {{unwrapVals: boolean}} options - if `unwrapVals` is passed,
+ * @param {import('../typedefs').resolver.EnumCSN} enumCsn - the CSN type describing the enum
+ * @param {{unwrapVals: boolean} | {}} options - if `unwrapVals` is passed,
  *  then the CSN structure `{val:x}` is flattened to just `x`.
  *  Retaining `val` is closer to the actual CSN structure and should be used where we want
  *  to mimic the runtime as closely as possible (inline enum types).
  *  Stripping that additional wrapper would be more readable for users.
+ * @returns {[string, any][]}
  * @example
  * ```ts
  * const csn = {enum: {X: {val: 'a'}, Y: {val: 'b'}, Z: {}}}
@@ -74,10 +82,10 @@ function printEnum(buffer, name, kvs, options = {}) {
  * ```
  */
 const csnToEnumPairs = ({enum: enm, type}, options = {}) => {
-    options = {...{unwrapVals: true}, ...options}
+    const actualOptions = {...{unwrapVals: true}, ...options}
     return Object.entries(enm).map(([k, v]) => {
         const val = enumVal(k, v.val, type)
-        return [k, (options.unwrapVals ? val : { val })]
+        return [k, (actualOptions.unwrapVals ? val : { val })]
     })
 }
 
@@ -91,11 +99,12 @@ const propertyToInlineEnumName = (entity, property) => `${entity}_${property}`
  * A type is considered to be an inline enum, iff it has a `.enum` property
  * _and_ its type is a CDS primitive, i.e. it is not contained in `cds.definitions`.
  * If it is contained there, then it is a standard enum declaration that has its own name.
- * @param {{type: string}} element - the element to check
- * @param {object} csn - the CSN model
- * @returns boolean
+ * @param {{type: string | import('../typedefs').resolver.ref, [key: string]: any}} element - the element to check
+ * @param {import('../typedefs').resolver.CSN} csn - the CSN model
+ * @returns {element is import('../typedefs').resolver.EnumCSN}
  */
-const isInlineEnumType = (element, csn) => element.enum && !(element.type in csn.definitions)
+const isInlineEnumType = (element, csn) => element.enum
+    && !(typeof element.type === 'string' && element.type in csn.definitions)
 
 /**
  * Stringifies an enum into a runtime artifact.

package/lib/components/identifier.js

@@ -15,7 +15,7 @@ const normalise = ident => ident && !isValidIdent.test(ident)
  * @param {string} ident - the identifier to extract the last part from
  * @returns {string} the last part of the identifier
  */
-const last = ident => ident.split('.').at(-1)
+const last = ident => ident.split('.').at(-1) ?? ident
 
 module.exports = {
     normalise,

package/lib/components/inline.js

@@ -3,6 +3,10 @@ const { normalise } = require('./identifier')
 const { docify } = require('./wrappers')
 
 /** @typedef {import('../resolution/resolver').TypeResolveInfo} TypeResolveInfo */
+/** @typedef {import('../typedefs').visitor.Inflection} Inflection */
+/** @typedef {import('../typedefs').resolver.PropertyModifier} PropertyModifier */
+/** @typedef {import('../visitor').Visitor} Visitor */
+/** @typedef {{typeName: string, typeInfo: TypeResolveInfo}} TypeResolveInfo_ */
 
 /**
  * Inline declarations of types can come in different flavours.
@@ -12,15 +16,17 @@ const { docify } = require('./wrappers')
  */
 class InlineDeclarationResolver {
     /**
-     * @param {string} fq - full qualifier of the type
-     * @param {TypeResolveInfo} type - type info so far
-     * @param {import('../file').Buffer} buffer - the buffer to write into
-     * @param {string} statementEnd - statement ending character
+     * @param {object} options - options to be passed to the resolver
+     * @param {string} options.fq - full qualifier of the type
+     * @param {TypeResolveInfo_} options.type - type info so far
+     * @param {import('../file').Buffer} options.buffer - the buffer to write into
+     * @param {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
+     * @param {string} [options.statementEnd] - statement ending character
      * @protected
      * @abstract
      */
     // eslint-disable-next-line no-unused-vars
-    printInlineType(fq, type, buffer, statementEnd) { /* abstract */ }
+    printInlineType({fq, type, buffer, modifiers, statementEnd}) { /* abstract */ }
 
     /**
      * Attempts to resolve a type that could reference another type.
@@ -39,6 +45,8 @@ class InlineDeclarationResolver {
         for (const [subname, subelement] of Object.entries(items ?? {})) {
             // in inline definitions, we sometimes have to resolve first
             // FIXME: does this tie in with how we sometimes end up with resolved typed in resolveType()?
+            // FIXME2: I don't think the if branch is actually called in real world situations.
+            // so we can probably get rid of this distinction and make #resolveTypeName private again
             const se = (typeof subelement === 'string')
                 ? this.visitor.resolver.resolveTypeName(subelement)
                 : subelement
@@ -58,13 +66,15 @@ class InlineDeclarationResolver {
 
     /**
      * Visits a single element in an entity.
-     * @param {string} name - name of the element
-     * @param {import('../resolution/resolver').CSN} element - CSN data belonging to the the element.
-     * @param {SourceFile} file - the namespace file the surrounding entity is being printed into.
-     * @param {Buffer} [buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @param {object} options - options
+     * @param {string} options.name - name of the element
+     * @param {import('../typedefs').resolver.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 {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
      * @public
      */
-    visitElement(name, element, file, buffer = file.classes) {
+    visitElement({name, element, file, buffer = file.classes, modifiers = []}) {
         this.depth++
         for (const d of docify(element.doc)) {
             buffer.add(d)
@@ -72,7 +82,7 @@ class InlineDeclarationResolver {
         const type = this.visitor.resolver.resolveAndRequire(element, file)
         this.depth--
         if (this.depth === 0) {
-            this.printInlineType(name, type, buffer)
+            this.printInlineType({fq: name, type, buffer, modifiers})
         }
         return type
     }
@@ -89,7 +99,7 @@ class InlineDeclarationResolver {
 
     /**
      * It returns TypeScript datatype for provided TS property
-     * @param {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection } }} type - type of the property
+     * @param {TypeResolveInfo_} type - type of the property
      * @param {string} typeName - name of the TypeScript property
      * @returns {string} the datatype to be presented on TypeScript layer
      * @public
@@ -98,7 +108,16 @@ class InlineDeclarationResolver {
         return type.typeInfo.isNotNull ? typeName : `${typeName} | null`
     }
 
-    /** @param {import('../visitor').Visitor} visitor - the visitor */
+    /**
+     * Stringifies additional modifiers for a property
+     * @param {(PropertyModifier)[]} modifiers - modifiers to stringify
+     * @returns {string} the modifiers as a string
+     */
+    stringifyModifiers (modifiers) {
+        return modifiers?.length > 0 ? modifiers.join(' ') + ' ' : ''
+    }
+
+    /** @param {Visitor} visitor - the visitor */
     constructor(visitor) {
         this.visitor = visitor
         // type resolution might recurse. This indicator is used to determine
@@ -148,24 +167,42 @@ class InlineDeclarationResolver {
  * ```
  */
 class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
-    constructor(visitor) { super(visitor) }
-
+    /**
+     * @param {string} p - prefix to use
+     */
     prefix(p) {
         return p ? `${p}_` : ''
     }
 
-    flatten(prefix, type) {
+    /**
+     * @param {object} options - options
+     * @param {string} options.prefix - prefix to use
+     * @param {TypeResolveInfo_} options.type - type to flatten
+     * @param {PropertyModifier[]} options.modifiers - modifiers to add to each generated property
+     * @returns {string[]} the flattened properties
+     */
+    flatten({prefix, type, modifiers}) {
         return type.typeInfo.structuredType
-            ? Object.entries(type.typeInfo.structuredType).map(([k,v]) => this.flatten(`${this.prefix(prefix)}${k}`, v))
-            : [`${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
+            ? Object.entries(type.typeInfo.structuredType).map(
+                ([k,v]) => this.flatten({prefix: `${this.prefix(prefix)}${k}`, type: v, modifiers})  // for flat we pass the modifiers!
+            ).flat()
+            : [`${this.stringifyModifiers(modifiers)}${normalise(prefix)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}`]
     }
 
-    printInlineType(name, type, buffer) {
-        for(const prop of this.flatten(name, type).flat()) {
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['printInlineType']}
+     */
+    printInlineType({fq, type, buffer, modifiers}) {
+        for(const prop of this.flatten({prefix: fq, type, modifiers}).flat()) {
             buffer.add(prop)
         }
     }
 
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['getTypeLookup']}
+     */
     getTypeLookup(members)  {
         return `['${members.join('_')}']`
     }
@@ -189,39 +226,57 @@ class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
  * ```
  */
 class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
+    /** @param {Visitor} visitor - the visitor */
     constructor(visitor) {
         super(visitor)
         this.printDepth = 0
     }
 
-    flatten(name, type, buffer, statementEnd = ';') {
+    /**
+     * @param {object} options - options
+     * @param {string} options.fq - full qualifier of the type
+     * @param {TypeResolveInfo_} options.type - type info so far
+     * @param {Buffer} options.buffer - the buffer to write into
+     * @param {PropertyModifier[]} [options.modifiers] - modifiers to add to each generated property
+     * @param {string} [options.statementEnd] - statement ending character
+     * FIXME: reuse type
+     */
+    flatten({fq, type, buffer, modifiers = [], statementEnd = ';'}) {
         // in addition to the regular depth during resolution, we may have another depth while printing
         // nested types on which the line ending depends
         this.printDepth++
         const lineEnding = this.printDepth > 1 ? ',' : statementEnd
         if (type.typeInfo.structuredType) {
-            const prefix = name ? `${normalise(name)}${this.getPropertyTypeSeparator()}`: ''
+            const prefix = fq ? `${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()}`: ''
             buffer.add(`${prefix} {`)
             buffer.indent()
             for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
-                this.flatten(n, t, buffer)
+                this.flatten({fq: n, type: t, buffer})
             }
             buffer.outdent()
             buffer.add(`}${this.getPropertyDatatype(type, '')}${lineEnding}`)
         } else {
-            buffer.add(`${normalise(name)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
+            buffer.add(`${this.stringifyModifiers(modifiers)}${normalise(fq)}${this.getPropertyTypeSeparator()} ${this.getPropertyDatatype(type)}${lineEnding}`)
         }
         this.printDepth--
         return buffer
     }
 
-    printInlineType(name, type, buffer, statementEnd) {
+    /**
+     * @override
+     * @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(name, type, sub, statementEnd).join())
+        buffer.add(this.flatten({fq, type, buffer: sub, modifiers, statementEnd}).join())
     }
 
+    /**
+     * @override
+     * @type {InlineDeclarationResolver['getTypeLookup']}
+     */
     getTypeLookup(members)  {
         return members.map(m => `['${m}']`).join('')
     }

package/lib/components/javascript.js

@@ -0,0 +1,28 @@
+/* eslint-disable no-undef */
+// this function will be stringified as part of the generated types and is not supposed to be used internally
+// @ts-nocheck
+const proxyAccessFunction = function (fqParts, opts = {}) {
+    const { target, customProps } = { target: {}, customProps: [], ...opts }
+    const fq = fqParts.join('.')
+    return new Proxy(target, {
+        get: function (target, prop) {
+            if (cds.entities) {
+                target.__proto__ = cds.entities[fq]
+                // overwrite/simplify getter after cds.entities is accessible
+                this.get = (target, prop) => target[prop]
+                return target[prop]
+            }
+            // we already know the name so we skip the cds.entities proxy access
+            if (prop === 'name') return fq
+            // custom properties access on 'target' as well as cached _entity property access goes here
+            if (Object.hasOwn(target, prop)) return target[prop]
+            // inline enums have to be caught here for first time access, as they do not exist on the entity
+            if (customProps.includes(prop)) return target[prop]
+            // last but not least we pass the property access to cds.entities
+            throw new Error(`Property ${prop} does not exist on entity '${fq}' or cds.entities is not yet defined. Ensure the CDS runtime is fully booted before accessing properties.`)
+        }
+    })
+}.toString()
+/* eslint-enable no-undef */
+
+module.exports = { proxyAccessFunction }

package/lib/components/property.js

@@ -0,0 +1,12 @@
+/**
+ * Determines the proper modifiers for a property.
+ * For most properties, this will be "declare". But for some properties,
+ * like fields of a type, we don't want any modifiers.
+ * @param {import('../typedefs').resolver.EntityCSN} element - The element to determine the modifiers for.
+ * @returns {import('../typedefs').resolver.PropertyModifier[]} The modifiers for the property.
+ */
+const getPropertyModifiers = element => element?.parent?.kind !== 'type' ? ['declare'] : []
+
+module.exports = {
+    getPropertyModifiers
+}

package/lib/components/wrappers.js

@@ -45,6 +45,24 @@ const createArrayOf = t => `Array<${t}>`
  */
 const createObjectOf = t => `{${t}}`
 
+/**
+ * Wraps types into a union type string
+ * @param {string[]} types - an array of types
+ * @returns {string}
+ */
+const createUnionOf = (...types) => types.join(' | ')
+
+/**
+ * Wraps type into a promise
+ * @param {string} t - the type to wrap.
+ * @returns {string}
+ * @example
+ * ```js
+ * createPromiseOf('string') // -> 'Promise<string>'
+ * ```
+ */
+const createPromiseOf = t => `Promise<${t}>`
+
 /**
  * Wraps type into a deep require (removes all posibilities of undefined recursively).
  * @param {string} t - the singular type name.
@@ -55,17 +73,22 @@ const deepRequire = (t, lookup = '') => `${base}.DeepRequired<${t}>${lookup}`
 
 /**
  * Puts a passed string in docstring format.
- * @param {string} doc - raw string to docify. May contain linebreaks.
+ * @param {string | undefined} doc - raw string to docify. May contain linebreaks.
  * @returns {string[]} an array of lines wrapped in doc format. The result is not
  *          concatenated to be properly indented by `buffer.add(...)`.
  */
-const docify = doc => doc
-    ? ['/**'].concat(doc.split('\n').map(line => `* ${line}`)).concat(['*/'])
-    : []
+const docify = doc => {
+    if (!doc) return []
+    const lines = doc.split(/\r?\n/).map(l => l.trim().replaceAll('*/', '*\\/')) // mask any */ with *\/
+    if (lines.length === 1) return [`/** ${lines[0]} */`] // one-line doc
+    return ['/**'].concat(lines.map(line => `* ${line}`)).concat(['*/'])
+}
 
 module.exports = {
     createArrayOf,
     createObjectOf,
+    createPromiseOf,
+    createUnionOf,
     createToOneAssociation,
     createToManyAssociation,
     createCompositionOfOne,