@cap-js/cds-typer 0.34.0 → 0.36.0

package/lib/boilerplate/tsBoilerplate.ts

@@ -0,0 +1,95 @@
+import cds from '@sap/cds'
+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 {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export namespace Composition {
+    export type of <T> = T;
+    export namespace of {
+        export type many <T extends readonly any[]> = T;
+    }
+}
+
+export class Entity {
+    static data<T extends Entity> (this:T, _input:Object) : T {
+        return {} as T // mock
+    }
+}
+
+export type EntitySet<T> = T[] & {
+    data (input:object[]) : 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<Unkey<T[K]>>
+} & Exclude<Required<T>, null>;
+
+const key = Symbol('key')  // to avoid .key showing up in IDE's auto-completion
+export type Key<T> = T & {[key]?: true}
+
+export type KeysOf<T> = {
+  [K in keyof T as NonNullable<T[K]> extends Key<unknown> ? K : never]-?: Key<{}>  // T[K] 
+}
+
+export type Unkey<T> = T extends Key<infer U> ? U : T
+
+/**
+ * Dates and timestamps are strings during runtime, so cds-typer represents them as such.
+ */
+export type CdsDate = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsDateTime = string;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsTime = `${number}${number}:${number}${number}:${number}${number}`;
+/**
+ * @see {@link CdsDate}
+ */
+export type CdsTimestamp = string;
+
+export type CdsMap = { [key: string]: unknown };
+
+
+export const createEntityProxy = function (fqParts: any, opts = {}) {
+    const { target, customProps } = { target: {}, customProps: [], ...opts }
+    const fq = fqParts.filter((p: any) => !!p).join('.')
+    return new Proxy(target, {
+        get: function (target:any, prop:any) {
+            if (cds.entities) {
+                target.__proto__ = cds.entities(fqParts[0])[fqParts[1]]
+                // 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 as never)) 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.`)
+        }
+    })
+}

package/lib/components/basedefs.js

@@ -1,88 +1,31 @@
 const { SourceFile } = require('../file')
+const fs = require('node:fs')
+const path = require('node:path')
 
-// eslint-disable-next-line no-template-curly-in-string
-const dateRegex = '`${number}${number}${number}${number}-${number}${number}-${number}${number}`'
-// eslint-disable-next-line no-template-curly-in-string
-const timeRegex = '`${number}${number}:${number}${number}:${number}${number}`'
+/** @type {string} */
+let tsBoilerplate
+/** @type {SourceFile} */
+let baseDefinitions
 
 /**
- * Base definitions used throughout the typing process,
- * such as Associations and Compositions.
- * @type {SourceFile}
+ * @returns {string}
  */
-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 {
-        export type many <T extends readonly any[]> = T;
+function getTsBoilerplate () {
+    if (!tsBoilerplate) {
+        tsBoilerplate = fs.readFileSync(path.join(__filename, '..', '..', 'boilerplate/tsBoilerplate.ts'), 'utf8')
     }
+    return tsBoilerplate
 }
 
-export namespace Composition {
-    export type of <T> = T;
-    export namespace of {
-        export type many <T extends readonly any[]> = T;
-    }
-}
-
-export class Entity {
-    static data<T extends Entity> (this:T, _input:Object) : T {
-        return {} as T // mock
-    }
-}
-
-export type EntitySet<T> = T[] & {
-    data (input:object[]) : 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<Unkey<T[K]>>
-} & Exclude<Required<T>, null>;
-
-const key = Symbol('key')  // to avoid .key showing up in IDE's auto-completion
-export type Key<T> = T & {[key]?: true}
-
-export type KeysOf<T> = {
-  [K in keyof T as NonNullable<T[K]> extends Key<unknown> ? K : never]-?: Key<{}>  // T[K] 
-}
-
-export type Unkey<T> = T extends Key<infer U> ? U : T
-
 /**
- * Dates and timestamps are strings during runtime, so cds-typer represents them as such.
+ * @returns {SourceFile}
  */
-export type CdsDate = ${dateRegex};
-/**
- * @see {@link CdsDate}
- */
-export type CdsDateTime = string;
-/**
- * @see {@link CdsDate}
- */
-export type CdsTime = ${timeRegex};
-/**
- * @see {@link CdsDate}
- */
-export type CdsTimestamp = string;
-
-export type CdsMap = { [key: string]: unknown };
-`)
+function getBaseDefinitions () {
+    if (!baseDefinitions) {
+        baseDefinitions = new SourceFile('_')
+        baseDefinitions.addPreamble(getTsBoilerplate())
+    }
+    return baseDefinitions
+}
 
-module.exports = { baseDefinitions }
+module.exports = { getBaseDefinitions }

package/lib/components/enum.js

@@ -124,7 +124,6 @@ const isInlineEnumType = (element, csn) => element.enum
  * @param {[string, string][]} kvs - a list of key-value pairs. Values that are falsey are replaced by
  * @param {import('../printers/javascript').Printer} jsp - the printer to use
  */
-// ??= for inline enums. If there is some static property of that name, we don't want to override it (for example: ".actions"
 const stringifyEnumImplementation = (name, kvs, jsp) => jsp.printExport(
     name,
     `{ ${kvs.map(([k,v]) => `${normalise(k)}: ${v}`).join(', ')} }`,

package/lib/file.js

@@ -471,7 +471,7 @@ class SourceFile extends File {
         const boilerplate = [AUTO_GEN_NOTE]
         if (configuration.useEntitiesProxy) {
             if (namespace === '_') {
-                boilerplate.push(jsp.printImport('cds', '@sap/cds'), this.#getEntityProxyFunctionExport())
+                boilerplate.push(jsp.printDefaultImport('cds', '@sap/cds'), this.#getEntityProxyFunctionExport())
             } else {
                 boilerplate.push(
                     jsp.printDeconstructedImport(

package/lib/printers/javascript.js

@@ -33,6 +33,17 @@ class JavaScriptPrinter {
         throw Error('not implemented')
     }
 
+    /**
+     * @abstract
+     * @param {string} alias - what the import should be known as within the importing file
+     * @param {string} from - the package/ location to import from
+     * @returns {string}
+     */
+    // eslint-disable-next-line no-unused-vars
+    printDefaultImport (alias, from) {
+        throw Error('not implemented')
+    }
+
     /**
      * @abstract
      * @param {string[]} imports - the deconstructed elements
@@ -83,6 +94,11 @@ class ESMPrinter extends JavaScriptPrinter {
         return `import * as ${alias} from '${from}'`
     }
 
+    /** @type {JavaScriptPrinter['printDefaultImport']} */
+    printDefaultImport (alias, from) {
+        return `import ${alias} from '${from}'`
+    }
+
     /** @type {JavaScriptPrinter['printDeconstructedImport']} */
     printDeconstructedImport (imports, from) {
         return `import { ${imports.join(', ')} } from '${from}/index.js'`
@@ -115,6 +131,11 @@ class CJSPrinter extends JavaScriptPrinter {
         return `const ${alias} = require('${from}')`
     }
 
+    /** @type {JavaScriptPrinter['printDefaultImport']} */
+    printDefaultImport (alias, from) {
+        return `const ${alias} = require('${from}')`
+    }
+
     /** @type {JavaScriptPrinter['printDeconstructedImport']} */
     printDeconstructedImport (imports, from) {
         return `const { ${imports.join(', ')} } = require('${from}')`

package/lib/resolution/resolver.js

@@ -8,13 +8,15 @@ const { StructuredInlineDeclarationResolver } = require('../components/inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('../components/enum')
 const { isReferenceType } = require('../components/reference')
 const { isEntity, getMaxCardinality } = require('../csn')
-const { baseDefinitions } = require('../components/basedefs')
+const { getBaseDefinitions } = require('../components/basedefs')
 const { BuiltinResolver } = require('./builtin')
 const { LOG } = require('../logging')
 const { last } = require('../components/identifier')
 const { getPropertyModifiers } = require('../components/property')
 const { configuration } = require('../config')
 
+const baseDefinitions = getBaseDefinitions()
+
 /** @typedef {import('../visitor').Visitor} Visitor */
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
 /** @typedef {import('../typedefs').resolver.EntityCSN} EntityCSN */
@@ -68,6 +70,14 @@ class Resolver {
         return type.items ? !type.items.notNull : !type.notNull
     }
 
+    /**
+     * @param {EntityCSN} type - a CSN type
+     * @returns {boolean} whether the type has the @mandatory annotation
+     */
+    isMandatory(type) {
+        return type['@mandatory'] === true
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}
@@ -302,11 +312,24 @@ class Resolver {
                 }[element.constructor.name] ?? []
 
             if (toOne && toMany) {
-                /** @type { EntityCSN | { type: string } } */
-                // @ts-expect-error - nope, it is not undefined
-                const target = element.items ?? (typeof element.target === 'string'
-                    ? { type: element.target }
-                    : element.target)
+                /**
+                 * Resolve a property from a CSN entity. If it is a reference, leave it as is.
+                 * If it is a string, return an object with type set to the string.
+                 * @param {Record<string, any>} el - the element to check
+                 * @param {string} property - the property to check
+                 * @returns {import('../typedefs').resolver.EntityCSN | { type: string }}
+                 */
+                const getTarget = (el, property) => typeof el[property] === 'string'
+                    ? { type: el[property] }
+                    : el[property]
+
+                /** @type { EntityCSN | { type: string } | undefined } */
+                const target = element.items
+                    ?? getTarget(element, 'target')
+                    ?? getTarget(element, 'targetAspect')  // Composition of aspects
+                if (!target) {
+                    throw new Error(`Could not resolve target of ${element}`)
+                }
                 /** set `notNull = true` to avoid repeated `| not null` TS construction */
                 // @ts-expect-error - yes, we know that notNull is not part of the type in some cases
                 target.notNull = true
@@ -475,6 +498,11 @@ class Resolver {
                 : element?.key || element?.notNull || cardinality > 1,
         }
 
+        // parameters with @mandatory are always not null
+        // as of today, it is not clear if this also applies to other fields annotated with @mandatory.
+        result.isNotNull ||= element.kind === 'param' && this.isMandatory(element)
+
+
         if (element?.type === undefined) {
             // "fallback" type "empty object". May be overriden via #resolveInlineDeclarationType
             // later on with an inline declaration
@@ -521,9 +549,10 @@ class Resolver {
             result.isBuiltin = true
             this.resolveType(element.items, file)
             //delete element.items
-        } else if (element?.elements && (options?.forceInlineStructs || !element?.type)) {
+        } else if (!result.isBuiltin && element?.elements && (options?.forceInlineStructs || !element?.type)) {
             // explicitly skip named type definitions, which have elements too, but should not be considered inline declarations
             // if the resolver option `forceInlineStructs` is `true`, named types in elements will be converted to inline
+            // Skipping isBuiltin will skip cds.Map, which has elements
             this.#resolveInlineDeclarationType(element.elements, result, file, options)
         }
 

package/lib/typedefs.d.ts

@@ -27,6 +27,7 @@ export module resolver {
         name: string,
         '@singular'?: string,
         '@plural'?: string,
+        '@mandatory'?: boolean,
         '@odata.draft.enabled'?: boolean // custom!
         _unresolved?: boolean
         isRefNotNull?: boolean // custom!

package/lib/visitor.js

@@ -10,7 +10,7 @@ const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf,
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
-const { baseDefinitions } = require('./components/basedefs')
+const { getBaseDefinitions } = require('./components/basedefs')
 const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
@@ -18,6 +18,9 @@ const { configuration } = require('./config')
 const { createMember } = require('./components/class')
 const { overrideNameProperty } = require('./printers/javascript')
 
+const baseDefinitions = getBaseDefinitions()
+const MAX_TRANSITIVE_RESOLUTION_STEPS = 10
+
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
@@ -274,6 +277,31 @@ class Visitor {
                     }))
                     if (typeof e?.type !== 'string' && e?.type?.ref) {
                         e.resolvedType = /** @type {string} */(lookUpRefType(this.csn, e.type.ref)?.type)
+                        try {
+                            /**
+                             * multi-level resolution does not contain a .ref property:
+                             * ```cds
+                             * entity A {
+                             *   x: enum ...
+                             * }
+                             * entity B {
+                             *   x: A:x
+                             * }
+                             * entity C {
+                             *   x: B:x
+                             * }
+                             * ```
+                             * results in B.x having a ref to [A,x], but C.x only has a string 'A.x' as type.
+                             * So we have to do yet another round of resolution on this string.
+                             * We attempt to follow this chain for MAX_TRANSITIVE_RESOLUTION_STEPS tops,
+                             * but we could finish earlier, when the type is a primitive ("string"), which
+                             * then jumps to the catch {} to leave e.resolvedType at the last, resolvable type.
+                             */
+                            for (let i = 0; i < MAX_TRANSITIVE_RESOLUTION_STEPS; i++) {
+                                const { csn } = this.resolver.resolveTypeName(/** @type {string} */(e.resolvedType))
+                                e.resolvedType = csn.type
+                            }
+                        } catch { /* ignore */ }
                     }
                     file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), buffer, eDoc)
                 }
@@ -403,7 +431,9 @@ class Visitor {
             .filter(([, type]) => type?.type !== '$self' && type.items?.type !== '$self')
             .map(([name, type]) => ({
                 name,
-                modifier: this.resolver.isOptional(type) ? '?' : '',
+                modifier: this.resolver.isOptional(type) && !this.resolver.isMandatory(type)
+                    ? '?'
+                    : '',
                 type: this.#stringifyFunctionParamType(type, file),
                 doc: docify(type.doc).join('\n'),
             }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.34.0",
+  "version": "0.36.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",
@@ -48,7 +48,7 @@
     "@stylistic/eslint-plugin-js": "^4.2.0",
     "acorn": "^8.10.0",
     "eslint": "^9",
-    "eslint-plugin-jsdoc": "^50.2.2",
+    "eslint-plugin-jsdoc": "^51.2.1",
     "typescript": ">=4.6.4"
   },
   "cds": {