@cap-js/cds-typer 0.24.0 → 0.26.0

package/lib/resolution/resolver.js

@@ -12,11 +12,14 @@ const { baseDefinitions } = require('../components/basedefs')
 const { BuiltinResolver } = require('./builtin')
 const { LOG } = require('../logging')
 const { last } = require('../components/identifier')
+const { getPropertyModifiers } = require('../components/property')
 
 /** @typedef {import('../visitor').Visitor} Visitor */
 /** @typedef {import('../typedefs').resolver.CSN} CSN */
+/** @typedef {import('../typedefs').resolver.EntityCSN} EntityCSN */
 /** @typedef {import('../typedefs').resolver.TypeResolveInfo} TypeResolveInfo */
-/** @typedef {import('../typedefs').visitor.Inflection} TypeResolveInfo */
+/** @typedef {import('../typedefs').visitor.Inflection} Inflection */
+/** @typedef {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection }}} ResolveAndRequireInfo */
 
 class Resolver {
     get csn() { return this.visitor.csn.inferred }
@@ -55,6 +58,15 @@ class Resolver {
         return this.existsInCsn(fq) || Boolean(this.builtinResolver.resolveBuiltin(fq))
     }
 
+    /**
+     * @param {EntityCSN} type - a CSN type
+     * @returns {boolean} whether the type is configured to be optional
+     */
+    isOptional(type) {
+        // TODO temporary solution to determine optional parameters. Align w/ compiler/importer.
+        return Object.keys(type).some(k => k.startsWith('@Core.OptionalParameter'))
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}
@@ -86,7 +98,7 @@ class Resolver {
         return {
             namespace: new Path(ns.split('.')),
             scope: nameParts.slice(0, -1),
-            name: nameParts.at(-1),
+            name: nameParts.at(-1) ?? nameAndProperty,
             property
         }
     }
@@ -146,10 +158,16 @@ class Resolver {
         const parts = p.split('.')
         if (parts.length <= 1) return []
 
-        const isPropertyOf = (property, entity) => entity && property && Object.hasOwn(entity?.elements, property)
+        /**
+         * @param {string} property
+         * @param {import('../typedefs').resolver.EntityCSN} entity
+         */
+        const isPropertyOf = (property, entity) => property && Object.hasOwn(entity?.elements ?? {}, property)
 
         const defs = this.visitor.csn.inferred.definitions
         // assume parts to contain [Namespace, Service, Entity1, Entity2, Entity3, property1, property2]
+        /** @type {string} */
+        // @ts-expect-error - nope, we know there is at least one element
         let qualifier = parts.shift()
         // find first entity from left (Entity1)
         while ((!defs[qualifier] || !isEntity(defs[qualifier])) && parts.length) {
@@ -175,7 +193,7 @@ class Resolver {
      * - inline type definitions, which don't really have a linguistic plural,
      *   but need to expressed as array type to be consumable by the likes of Composition.of.many<T>
      * @param {import('./resolver').TypeResolveInfo} typeInfo - information about the type gathered so far.
-     * @param {string} [namespace] - namespace the type occurs in. If passed, will be shaved off from the name
+     * @param {string | import('../file').Path} [namespace] - namespace the type occurs in. If passed, will be shaved off from the name
      * @returns {Inflection}
      */
     inflect(typeInfo, namespace) {
@@ -189,7 +207,11 @@ class Resolver {
             }
         }
 
-        let typeName
+        if (namespace instanceof Path) {
+            namespace = namespace.asNamespace()
+        }
+
+        let typeName = ''
         let singular
         let plural
 
@@ -204,7 +226,13 @@ class Resolver {
             // If stringifyLambda(...) is the only place where we need this, we should have stringifyLambda call this
             // piece of code instead to reduce overhead.
             const into = new Buffer()
-            this.structuredInlineResolver.printInlineType(undefined, { typeInfo }, into, '')
+            this.structuredInlineResolver.printInlineType({
+                fq: '',
+                type: { typeInfo, typeName: '' },
+                buffer: into,
+                statementEnd: '',
+                modifiers: getPropertyModifiers(typeInfo.csn)
+            })
             typeName = into.join(' ')
             singular = typeName
             plural = createArrayOf(typeName)
@@ -246,9 +274,9 @@ class Resolver {
      * 1. add an import of model1 to model2 with proper path resolution and alias, e.g. "import * as m1 from './model1'"
      * 2. resolve any singular/ plural issues and association/ composition around it
      * 3. return a properly prefixed name to use within model2.d.ts, e.g. "m1.Foo"
-     * @param {CSN} element - the CSN element to resolve the type for.
+     * @param {import('../visitor').EntityCSN} element - the CSN element to resolve the type for.
      * @param {SourceFile} file - source file for context.
-     * @returns {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection } }} info about the resolved type
+     * @returns {ResolveAndRequireInfo} info about the resolved type
      */
     resolveAndRequire(element, file) {
         const typeInfo = this.resolveType(element, file)
@@ -266,9 +294,15 @@ class Resolver {
                 }[element.constructor.name] ?? []
 
             if (toOne && toMany) {
-                const target = element.items ?? (typeof element.target === 'string' ? { type: element.target } : element.target)
+                /** @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)
                 /** 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
+                // @ts-expect-error - yes, target is a valid parameter
                 const targetTypeInfo = this.resolveAndRequire(target, file)
                 if (targetTypeInfo.typeInfo.isDeepRequire === true) {
                     typeName = cardinality > 1 ? toMany(targetTypeInfo.typeName) : toOne(targetTypeInfo.typeName)
@@ -280,7 +314,7 @@ 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.visitor.entityRepository.getByFq(target.type)
+                        const untangled = this.visitor.entityRepository.getByFqOrThrow(target.type)
                         const scope = untangled.scope.join('.')
                         if (scope && !singular.startsWith(scope)) {
                             singular = `${scope}.${singular}`
@@ -359,7 +393,7 @@ class Resolver {
      * Resolves the fully qualified name of an entity to its parent entity.
      * resolveParent(a.b.c.D) -> CSN {a.b.c}
      * @param {string} name - fully qualified name of the entity to resolve the parent of.
-     * @returns {CSN} the resolved parent CSN.
+     * @returns {import('../typedefs').resolver.EntityCSN} the resolved parent CSN.
      */
     resolveParent(name) {
         return this.csn.definitions[name.split('.').slice(0, -1).join('.')]
@@ -394,14 +428,20 @@ class Resolver {
     /**
      * Resolves an element's type to either a builtin or a user defined type.
      * Enriched with additional information for improved printout (see return type).
-     * @param {CSN} element - the CSN element to resolve the type for.
+     * @param {import('../typedefs').resolver.EntityCSN | TypeResolveInfo} element - the CSN element to resolve the type for.
      * @param {SourceFile} file - source file for context.
      * @returns {TypeResolveInfo} description of the resolved type
      */
     resolveType(element, file) {
         // 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.
-        if (element && Object.hasOwn(element, 'isBuiltin')) return element
+        // type guard check purely to satisfy return statement
+        /**
+         * @param {any} e - the element to check
+         * @returns {e is TypeResolveInfo}
+         */
+        const isBuiltin = e => Object.hasOwn(e ?? {}, 'isBuiltin')
+        if (isBuiltin(element)) return element
 
         const cardinality = getMaxCardinality(element)
 
@@ -447,7 +487,7 @@ class Resolver {
                 // this.#resolveInlineDeclarationType(element.enum, result, file)
                 // or
                 // stringifyEnumType(csnToEnumPairs(element))
-                this.#resolveTypeName(element.type, result)
+                this.resolveTypeName(element.type, result)
             }
         } else {
             this.resolvePotentialReferenceType(element.type, result, file)
@@ -482,7 +522,7 @@ class Resolver {
      * }
      *
      * These have to be resolved to a new type.
-     * @param {any[]} items - the properties of the inline declaration.
+     * @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.
      *  This is important to correctly detect when a field in the inline declaration is referencing
@@ -503,11 +543,11 @@ class Resolver {
         if (val.elements) {
             this.#resolveInlineDeclarationType(val, into, file) // FIXME INDENT!
         } else if (val.constructor === Object && 'ref' in val) {
-            this.#resolveTypeName(val.ref[0], into)
+            this.resolveTypeName(val.ref[0], into)
             into.isForeignKeyReference = true
         } else {
             // val is string
-            this.#resolveTypeName(val, into)
+            this.resolveTypeName(val, into)
         }
     }
 
@@ -516,11 +556,11 @@ class Resolver {
      * String is supposed to refer to either a builtin type
      * or any type defined in CSN.
      * @param {string} t - fully qualified type, like cds.String, or a.b.c.d.Foo
-     * @param {TypeResolveInfo} into - optional dictionary to fill by reference, see resolveType()
+     * @param {TypeResolveInfo} [into] - optional dictionary to fill by reference, see resolveType()
      * @returns @see resolveType
      */
-    #resolveTypeName(t, into) {
-        const result = into || {}
+    resolveTypeName(t, into) {
+        const result = into ?? {}
         const path = t.split('.')
         const builtin = this.builtinResolver.resolveBuiltin(path)
         if (builtin === undefined) {

package/lib/typedefs.d.ts

@@ -1,10 +1,56 @@
 export module resolver {
+    type ref = {
+        ref: string[],
+        as?: string
+    }
+
+    export type PropertyModifier = 'override' | 'declare'
+
     export type EntityCSN = {
-        cardinality?: { max?: '*' | number }
+        actions?: OperationCSN[],
+        operations?: OperationCSN[],
+        cardinality?: { max?: '*' | string }
+        compositions?: { target: string }[]
+        doc?: string,
+        elements?: { [key: string]: EntityCSN }
+        key?: string // custom!!
+        keys?: { [key:string]: any }
+        kind: string,
+        includes?: string[]
+        items?: EntityCSN
+        notNull?: boolean,  // custom!
+        on?: string,
+        parent?: EntityCSN
+        projection?: { from: ref, columns: (ref | '*')[]}
+        target?: string,
+        type: string | ref,
+        name: string,
+        '@odata.draft.enabled'?: boolean // custom!
+        _unresolved?: boolean
+        isRefNotNull?: boolean // custom!
+    }
+
+    export type OperationCSN = EntityCSN & {
+        params: {[key:string]: EntityCSN},
+        returns?: any,
+        kind: 'action' | 'function'
+    }
+
+    export type ProjectionCSN = EntityCSN & {
+        projection: any
+    }
+
+    export type ViewCSN = EntityCSN & {
+        query?: any
+    }
+
+
+    export type EnumCSN = EntityCSN & {
+        enum: {[key:name]: string}
     }
 
     export type CSN = {
-        definitions?: { [key: string]: EntityCSN }
+        definitions: { [key: string]: EntityCSN },
     }
 
     /**
@@ -19,19 +65,25 @@ export module resolver {
      * ```
      */
     export type TypeResolveInfo = {
-        isBuiltin: boolean,
-        isDeepRequire: boolean,
-        isNotNull: boolean,
-        isInlineDeclaration: boolean,
-        isForeignKeyReference: boolean,
-        isArray: boolean,
-        type: string,
+        isBuiltin?: boolean,
+        isDeepRequire?: boolean,
+        isNotNull?: boolean,
+        isInlineDeclaration?: boolean,
+        isForeignKeyReference?: boolean,
+        isArray?: boolean,
+        type?: string,
         path?: Path,
-        csn?: CSN,
-        imports: Path[]
-        inner: TypeResolveInfo
+        csn?: EntityCSNCSN,
+        imports?: Path[]
+        inner?: TypeResolveInfo,
+        structuredType?: {[key: string]: {typeName: string, typeInfo: TypeResolveInfo}}  // FIXME: same as inner?
+        plainName: string,
+        typeName?: string // FIXME: same as plainName?
+        inflection?: visitor.Inflection
     }
 
+    export type EntityInfo = Exclude<ReturnType<import('../lib/resolution/entity').EntityRepository['getByFq']>, null>
+
     // 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]`
@@ -67,7 +119,11 @@ export module visitor {
     export type CompileParameters = {
         outputDirectory: string,
         logLevel: number,
+        useEntitiesProxy: boolean,
         jsConfigPath?: string,
+        inlineDeclarations: 'flat' | 'structured',
+        propertiesOptional: boolean,
+        IEEE754Compatible: boolean,
     }
 
     export type VisitorOptions = {
@@ -78,10 +134,14 @@ export module visitor {
          * `inlineDeclarations = 'flat'` -> @see {@link inline.FlatInlineDeclarationResolver}
          */
         inlineDeclarations: 'flat' | 'structured',
+        /**
+         * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects
+         */
+        useEntitiesProxy: boolean
     }
 
     export type Inflection = {
-        typeName: string,
+        typeName?: string,
         singular: string,
         plural: string
     }
@@ -89,8 +149,18 @@ export module visitor {
     export type Context = {
         entity: string
     }
+
+    export type ParamInfo = {
+        name: string,
+        modifier: '' | '?',
+        type: string,
+        doc?: string
+    }
 }
 
 export module file {
     export type Namespace = Object<string, Buffer>
+    export type FileOptions = {
+        useEntitiesProxy: boolean
+    }
 }

package/lib/util.js

@@ -1,6 +1,7 @@
 /** @typedef { import('./typedefs').util.Annotations} Annotations */
 /** @typedef { import('./typedefs').util.CommandLineFlags } CommandlineFlag */
 /** @typedef { import('./typedefs').util.ParsedFlag } ParsedFlags */
+/** @typedef { import('./typedefs').resolver.EntityCSN } EntityCSN */
 
 // inflection functions are stolen from github/cap/dev/blob/main/etc/inflect.js
 
@@ -23,7 +24,7 @@ const annotations = {
  * from a CSN. Valid annotations are listed in util.annotations
  * and their precedence is in order of definition.
  * If no singular is specified at all, undefined is returned.
- * @param {object} csn - the CSN of an entity to check
+ * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the singular annotation or undefined
  */
 const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.hasOwn(csn, a))]
@@ -33,7 +34,7 @@ const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.h
  * from a CSN. Valid annotations are listed in util.annotations
  * and their precedence is in order of definition.
  * If no plural is specified at all, undefined is returned.
- * @param {object} csn - the CSN of an entity to check
+ * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the plural annotation or undefined
  */
 const getPluralAnnotation = csn => csn[annotations.plural.find(a => Object.hasOwn(csn, a))]
@@ -137,7 +138,7 @@ const deepMerge = (target, source) => {
  * @returns {ParsedFlags}
  */
 const parseCommandlineArgs = (argv, validFlags) => {
-    const isFlag = arg => arg.startsWith('--')
+    const isFlag = (/** @type {string} */ arg) => arg.startsWith('--')
     const positional = []
     const named = {}