@cap-js/cds-typer 0.22.0 → 0.23.0

package/lib/{components → resolution}/resolver.js

@@ -3,122 +3,25 @@
 const util = require('../util')
 // eslint-disable-next-line no-unused-vars
 const { Buffer, SourceFile, Path, Library } = require('../file')
-const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne } = require('./wrappers')
-const { StructuredInlineDeclarationResolver } = require('./inline')
-const { isInlineEnumType, propertyToInlineEnumName } = require('./enum')
-const { isReferenceType } = require('./reference')
-const { isEntity } = require('../csn')
-const { baseDefinitions } = require('./basedefs')
+const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne } = require('../components/wrappers')
+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 { BuiltinResolver } = require('./builtin')
+const { LOG } = require('../logging')
+const { last } = require('../components/identifier')
 
 /** @typedef {import('../visitor').Visitor} Visitor */
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
 /** @typedef {import('../typedefs').resolver.TypeResolveInfo} TypeResolveInfo */
-
-class BuiltinResolver {
-    /**
-     * Builtin types defined by CDS.
-     */
-    #builtins = {
-        UUID: 'string',
-        String: 'string',
-        Binary: 'string',
-        LargeString: 'string',
-        LargeBinary: 'Buffer | string | {value: import("stream").Readable, $mediaContentType: string, $mediaContentDispositionFilename?: string, $mediaContentDispositionType?: string}',
-        Vector: 'string',
-        Integer: 'number',
-        UInt8: 'number',
-        Int16: 'number',
-        Int32: 'number',
-        Int64: 'number',
-        Integer64: 'number',
-        Decimal: 'number',
-        DecimalFloat: 'number',
-        Float: 'number',
-        Double: 'number',
-        Boolean: 'boolean',
-        // note: the date-related types are strings on purpose, which reflects their runtime behaviour
-        Date: '__.CdsDate',  // yyyy-mm-dd
-        DateTime: '__.CdsDateTime', // yyyy-mm-dd + time + TZ (precision: seconds)
-        Time: '__.CdsTime',  // hh:mm:ss
-        Timestamp: '__.CdsTimestamp', // yyy-mm-dd + time + TZ (ms precision)
-        //
-        Composition: 'Array',
-        Association: 'Array'
-    }
-
-    constructor ({ IEEE754Compatible } = {}) {
-        if (IEEE754Compatible) {
-            this.#builtins.Decimal = '(number | string)'
-            this.#builtins.DecimalFloat = '(number | string)'
-            this.#builtins.Float = '(number | string)'
-            this.#builtins.Double = '(number | string)'
-        }
-        this.#builtins = Object.freeze(this.#builtins)
-    }
-
-    /**
-     * @param {string | string[]} t - name or parts of the type name split on dots
-     * @returns {string | undefined | false} if t refers to a builtin, the name of the corresponding TS type is returned.
-     *   If t _looks like_ a builtin (`cds.X`), undefined is returned.
-     *   If t is obviously not a builtin, false is returned.
-     */
-    resolveBuiltin (t) {
-        if (!Array.isArray(t) && typeof t !== 'string') return false
-        const path = Array.isArray(t) ? t : t.split('.')
-        return path.length === 2 && path[0] === 'cds'
-            ? this.#builtins[path[1]]
-            : false
-    }
-}
+/** @typedef {import('../typedefs').visitor.Inflection} TypeResolveInfo */
 
 class Resolver {
-
-    #caches = {
-        /**
-         * @type {{ [qualifier: string]: string }}
-         */
-        namespaces: {},
-        /**
-         * @type {{ [qualifier: string]: string[] }}
-         */
-        propertyAccesses: {}
-    }
-
-    /**
-     * @param {string} qualifier
-     * @returns {string?}
-     */
-    #getCachedNamespace (qualifier) {
-        return this.#caches.namespaces[qualifier]
-    }
-
-    /**
-     * @param {string} qualifier
-     * @param {string} namespace
-     */
-    #cacheNamespace (qualifier, namespace) {
-        this.#caches.namespaces[qualifier] = namespace
-    }
-
-    /**
-     * @param {string} qualifier
-     * @returns {string[]?}
-     */
-    #getCachedPropertyAccess (qualifier) {
-        return this.#caches.propertyAccesses[qualifier]
-    }
-
-    /**
-     * @param {string} qualifier
-     * @param {string[]} propertyAccess
-     */
-    #cachePropertyAccess (qualifier, propertyAccess) {
-        this.#caches.propertyAccesses[qualifier] = propertyAccess
-    }
-
     get csn() { return this.visitor.csn.inferred }
-    
-    /** @param {Visitor} visitor */
+
+    /** @param {Visitor} visitor - the visitor */
     constructor(visitor) {
         /** @type {Visitor} */
         this.visitor = visitor
@@ -134,8 +37,24 @@ class Resolver {
          * needed for inline declarations
          */
         this.structuredInlineResolver = new StructuredInlineDeclarationResolver(this.visitor)
-    }   
-    
+    }
+
+    /**
+     * @param {string} fq - fully qualified name of the entity
+     * @returns {boolean} true, iff the entity exists in the CSN (excluding builtins, see {@link isPartOfModel})
+     */
+    existsInCsn(fq) {
+        return Boolean(this.csn.definitions[fq])
+    }
+
+    /**
+     * @param {string} fq - fully qualified name of the entity or builtin
+     * @returns {boolean} true, iff the entity exists in the CSN or is identified as a builtin
+     */
+    isPartOfModel(fq) {
+        return this.existsInCsn(fq) || Boolean(this.builtinResolver.resolveBuiltin(fq))
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}
@@ -144,27 +63,19 @@ class Resolver {
         return this.libraries.filter(l => l.referenced)
     }
 
-    /**
-     * TODO: this should probably be a class where we can also cache the properties
-     * and only retrieve them on demand
-     * @typedef {object} Untangled 
-     * @property {string[]} scope in case the entity is wrapped in another entity `a.b.C.D.E.f.g` -> `[C,D]`
-     * @property {string} name name of the leaf entity `a.b.C.D.E.f.g` -> `E`
-     * @property {string[]} property the property access path `a.b.C.D.E.f.g` -> `[f,g]`
-     * @property {Path} namespace the cds namespace of the entity `a.b.C.D.E.f.g` -> `a.b`
-     */
-
     /**
      * Conveniently combines resolveNamespace and trimNamespace
      * to end up with both the resolved Path of the namespace,
      * and the clean name of the class.
      * @param {string} fq - the fully qualified name of an entity.
-     * @returns {Untangled} untangled qualifier
+     * @returns {import('../typedefs').resolver.Untangled} untangled qualifier
      */
     untangle(fq) {
         const builtin = this.builtinResolver.resolveBuiltin(fq)
         if (builtin) return { namespace: new Path([]), name: builtin, property: [], scope: [] }
 
+        // FIXME: if fq points to a service definition, ns will be the same as nameAndProperty
+        // this currently isn't a problem as we only use the its name, but should be addressed at some point
         const ns = this.resolveNamespace(fq)
         const nameAndProperty = this.trimNamespace(fq)
         const property = this.findPropertyAccess(fq)
@@ -172,7 +83,7 @@ class Resolver {
             ? nameAndProperty.slice(0, -(property.join('').length + property.length)) // +1 for each dot
             : nameAndProperty
         ).split('.')//.at(-1)  // nested entities would return Foo.Bar, so we only take the last part to get the actual entity name
-        return { 
+        return {
             namespace: new Path(ns.split('.')),
             scope: nameParts.slice(0, -1),
             name: nameParts.at(-1),
@@ -191,7 +102,6 @@ class Resolver {
      * @returns {string} the entity name without leading namespace.
      */
     trimNamespace(p) {
-        //if (this.#getCachedNamespace(p)) return this.#getCachedNamespace(p)
         const parts = p.split('.')
         if (parts.length <= 1) return p
 
@@ -218,13 +128,13 @@ class Resolver {
      * entity Entity {
      *   x: Composition of { y: Composition of z: { a: Integer }}
      * }
-     * 
+     *
      * // somewhere else
      * entity Foo {
      *   x: namespace.Entity.x.y.z;
      * }
      * ```
-     * @example 
+     * @example
      * ```js
      * findPropertyAccess('namespace') // []
      * findPropertyAccess('namespace.Entity') // []
@@ -233,7 +143,6 @@ class Resolver {
      * ```
      */
     findPropertyAccess(p) {
-        if (this.#getCachedPropertyAccess(p)) return this.#getCachedPropertyAccess(p)
         const parts = p.split('.')
         if (parts.length <= 1) return []
 
@@ -247,13 +156,12 @@ class Resolver {
             qualifier += `.${parts.shift()}`
         }
         // skip forward to the last entity from left (Entity3), assuming that there is no name conflict between entities and properties
-        // i.e.: if there is a property "Entity2" in the entity Entity1, this will instead [Entity2, Entity3, property1, property2] as property access 
+        // i.e.: if there is a property "Entity2" in the entity Entity1, this will instead [Entity2, Entity3, property1, property2] as property access
         while (!isPropertyOf(parts[0], defs[qualifier]) && isEntity(defs[qualifier + `.${parts[0]}`])) {
             qualifier += `.${parts.shift()}`
         }
         // assuming Entity3 _does_ own a property "property1", return [property1, property2]
         const propertyAccess = isPropertyOf(parts[0], defs[qualifier]) ? parts : []
-        this.#cachePropertyAccess(p, propertyAccess)
         return propertyAccess
     }
 
@@ -274,7 +182,7 @@ class Resolver {
         // TODO: handle builtins here as well?
         // guard: types don't get inflected
         if (typeInfo.csn?.kind === 'type') {
-            return { 
+            return {
                 singular: typeInfo.plainName,
                 plural: createArrayOf(typeInfo.plainName),
                 typeName: typeInfo.plainName,
@@ -318,7 +226,7 @@ class Resolver {
             }
         }
         if (!singular || !plural) {
-            this.visitor.logger.error(`Singular ('${singular}') or plural ('${plural}') for '${typeName}' is empty.`)
+            LOG.error(`Singular ('${singular}') or plural ('${plural}') for '${typeName}' is empty.`)
         }
 
         return { typeName, singular, plural }
@@ -344,7 +252,7 @@ class Resolver {
      */
     resolveAndRequire(element, file) {
         const typeInfo = this.resolveType(element, file)
-        const cardinality = this.getMaxCardinality(element)
+        const cardinality = getMaxCardinality(element)
 
         let typeName = typeInfo.plainName ?? typeInfo.type
 
@@ -372,14 +280,14 @@ class Resolver {
                     // But we can't just fix it in inflection(...), as that would break several other things
                     // So we bandaid-fix it back here, as it is the least intrusive place -- but this should get fixed asap!
                     if (target.type) {
-                        const untangled = this.untangle(target.type)
+                        const untangled = this.visitor.entityRepository.getByFq(target.type)
                         const scope = untangled.scope.join('.')
                         if (scope && !singular.startsWith(scope)) {
                             singular = `${scope}.${singular}`
                         }
                     }
 
-                    typeName = cardinality > 1 
+                    typeName = cardinality > 1
                         ? toMany(plural)
                         : toOne(this.visitor.isSelfReference(target) ? 'this' : singular)
                     file.addImport(baseDefinitions.path)
@@ -426,13 +334,13 @@ class Resolver {
         // handle typeof (unless it has already been handled above)
         const target = element.target?.name ?? element.type?.ref?.join('.') ?? element.type
         if (target && !typeInfo.isDeepRequire) {
-            const { property: propertyAccess } = this.untangle(target)
-            if (propertyAccess.length) {
+            const { propertyAccess } =  this.visitor.entityRepository.getByFq(target) ?? {}
+            if (propertyAccess?.length) {
                 const element = target.slice(0, -propertyAccess.join('.').length - 1)
                 const access = this.visitor.inlineDeclarationResolver.getTypeLookup(propertyAccess)
                 // singular, as we have to access the property of the entity
                 typeName = deepRequire(util.singular4(element)) + access
-                typeInfo.isDeepRequire = true          
+                typeInfo.isDeepRequire = true
             }
         }
 
@@ -447,18 +355,6 @@ class Resolver {
         return { typeName, typeInfo }
     }
 
-    /**
-     * Attempts to retrieve the max cardinality of a CSN for an entity.
-     * @param {EntityCSN} element - csn of entity to retrieve cardinality for
-     * @returns {number} max cardinality of the element.
-     * If no cardinality is attached to the element, cardinality is 1.
-     * If it is set to '*', result is Infinity.
-     */
-    getMaxCardinality(element) {
-        const cardinality = element?.cardinality?.max ?? 1
-        return cardinality === '*' ? Infinity : parseInt(cardinality)
-    }
-
     /**
      * Resolves the fully qualified name of an entity to its parent entity.
      * resolveParent(a.b.c.D) -> CSN {a.b.c}
@@ -480,8 +376,6 @@ class Resolver {
      */
     resolveNamespace(pathParts) {
         if (typeof pathParts === 'string') pathParts = pathParts.split('.')
-        const fq = pathParts.join('.')
-        if (this.#getCachedNamespace(fq)) return this.#getCachedNamespace(fq)
         let result
         while (result === undefined) {
             const path = pathParts.join('.')
@@ -494,7 +388,6 @@ class Resolver {
                 pathParts = pathParts.slice(0, -1)
             }
         }
-        this.#cacheNamespace(fq, result)
         return result
     }
 
@@ -510,15 +403,15 @@ class Resolver {
         // with an already resolved type. In that case, just return the type we have.
         if (element && Object.hasOwn(element, 'isBuiltin')) return element
 
-        const cardinality = this.getMaxCardinality(element)
+        const cardinality = getMaxCardinality(element)
 
         const result = {
             isBuiltin: false, // will be rectified in the corresponding handlers, if needed
             isInlineDeclaration: false,
             isForeignKeyReference: false,
             isArray: false,
-            isNotNull: element?.isRefNotNull !== undefined 
-                ? element?.isRefNotNull 
+            isNotNull: element?.isRefNotNull !== undefined
+                ? element?.isRefNotNull
                 : element?.key || element?.notNull || cardinality > 1,
         }
 
@@ -550,7 +443,7 @@ class Resolver {
                 // FIXME: this is the case where users have arrays of enums as action parameter type.
                 // Instead of building the proper type (e.g. `'A' | 'B' | ...`, we are instead building
                 // the encasing type (e.g. `string` here)
-                // We should instead aim for a proper type, i.e. 
+                // We should instead aim for a proper type, i.e.
                 // this.#resolveInlineDeclarationType(element.enum, result, file)
                 // or
                 // stringifyEnumType(csnToEnumPairs(element))
@@ -558,7 +451,7 @@ class Resolver {
             }
         } else {
             this.resolvePotentialReferenceType(element.type, result, file)
-        }            
+        }
 
         // objects and arrays
         if (element?.items) {
@@ -574,7 +467,7 @@ class Resolver {
         }
 
         if (result.isBuiltin === false && result.isInlineDeclaration === false && !result.plainName) {
-            this.logger.warning(`Plain name is empty for ${element?.type ?? '<empty>'}. This will probably cause issues.`)
+            LOG.warn(`Plain name is empty for ${element?.type ?? '<empty>'}. This will probably cause issues.`)
         }
         return result
     }
@@ -601,7 +494,7 @@ class Resolver {
 
     /**
      * Attempts to resolve a type that could reference another type.
-     * @param {?} val
+     * @param {?} val - the value
      * @param {TypeResolveInfo} into - see resolveType()
      * @param {SourceFile} file - only needed as we may call #resolveInlineDeclarationType from here. Will be expelled at some point.
      */
@@ -669,7 +562,7 @@ class Resolver {
                 // class Book { title: _cds_hana.cds.hana.VARCHAR }  // <- how it would be without discarding the namespace
                 // class Book { title: _cds_hana.VARCHAR } // <- how we want it to look
                 // ```
-                const plain = t.split('.').at(-1)
+                const plain = last(t)
                 lib.referenced = true
                 result.type = plain
                 result.isBuiltin = false
@@ -685,6 +578,4 @@ class Resolver {
     }
 }
 
-module.exports = {
-    Resolver
-}
+module.exports = { Resolver }

package/lib/typedefs.d.ts

@@ -31,6 +31,18 @@ export module resolver {
         imports: Path[]
         inner: TypeResolveInfo
     }
+
+    // TODO: this will be completely replaced by EntityInfo
+    export type Untangled = {
+        // scope in case the entity is wrapped in another entity `a.b.C.D.E.f.g` -> `[C,D]`
+        scope: string[],
+        // name name of the leaf entity `a.b.C.D.E.f.g` -> `E`
+        name: string,
+        // property the property access path `a.b.C.D.E.f.g` -> `[f,g]`
+        property: string[],
+        // namespace the cds namespace of the entity `a.b.C.D.E.f.g` -> `a.b`
+        namespace: Path
+    }
 }
 
 export module util {
@@ -59,7 +71,12 @@ export module visitor {
     }
 
     export type VisitorOptions = {
+        /** `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable) */
         propertiesOptional: boolean,
+        /**
+         * `inlineDeclarations = 'structured'` -> @see {@link inline.StructuredInlineDeclarationResolver}
+         * `inlineDeclarations = 'flat'` -> @see {@link inline.FlatInlineDeclarationResolver}
+         */
         inlineDeclarations: 'flat' | 'structured',
     }
 
@@ -68,6 +85,10 @@ export module visitor {
         singular: string,
         plural: string
     }
+
+    export type Context = {
+        entity: string
+    }
 }
 
 export module file {

package/lib/util.js

@@ -88,7 +88,7 @@ const singular4 = (dn, stripped = false) => {
 
 /**
  * Attempts to derive the plural form of an English noun.
- * If '@plural' is passed as annotation, that is preferred. 
+ * If '@plural' is passed as annotation, that is preferred.
  * @param {Annotations} dn - annotations
  * @param {boolean} stripped - if true, leading namespace will be stripped
  */
@@ -110,7 +110,7 @@ const plural4 = (dn, stripped) => {
 }
 
 /**
- * Performs a deep merge of the passed objects into the first object. 
+ * Performs a deep merge of the passed objects into the first object.
  * See Object.assign(target, source).
  * @param {object} target - object to assign into.
  * @param {object} source - object to assign from.
@@ -124,13 +124,13 @@ const deepMerge = (target, source) => {
 
 /**
  * Parses command line arguments into named and positional parameters.
- * Named parameters are expected to start with a double dash (--). 
+ * Named parameters are expected to start with a double dash (--).
  * If the next argument `B` after a named parameter `A` is not a named parameter itself,
  * `B` is used as value for `A`.
  * If `A` and `B` are both named parameters, `A` is just treated as a flag (and may receive a default value).
  * Only named parameters that occur in validFlags are allowed. Specifying named flags that are not listed there
  * will cause an error.
- * Named parameters that are either not specified or do not have a value assigned to them may draw a default value 
+ * Named parameters that are either not specified or do not have a value assigned to them may draw a default value
  * from their definition in validFlags.
  * @param {string[]} argv - list of command line arguments
  * @param {{[key: string]: CommandlineFlag}} validFlags - allowed flags. May specify default values.
@@ -157,9 +157,9 @@ const parseCommandlineArgs = (argv, validFlags) => {
                     named[arg] = validFlags[arg].default
                 }
 
-                const allowed = validFlags[arg].allowed
+                const { allowed, allowedHint } = validFlags[arg]
                 if (allowed && !allowed.includes(named[arg])) {
-                    throw new Error(`invalid value '${named[arg]}' for flag ${arg}. Must be one of ${allowed.join(', ')}`)
+                    throw new Error(`invalid value '${named[arg]}' for flag ${arg}. Must be one of ${(allowedHint ?? allowed.join(', '))}`)
                 }
             }
         } else {