@cap-js/cds-typer 0.26.0 → 0.28.0

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

@@ -3,7 +3,7 @@
 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('../components/wrappers')
+const { deepRequire, createToManyAssociation, createToOneAssociation, createArrayOf, createCompositionOfMany, createCompositionOfOne, createKey } = require('../components/wrappers')
 const { StructuredInlineDeclarationResolver } = require('../components/inline')
 const { isInlineEnumType, propertyToInlineEnumName } = require('../components/enum')
 const { isReferenceType } = require('../components/reference')
@@ -13,11 +13,13 @@ const { BuiltinResolver } = require('./builtin')
 const { LOG } = require('../logging')
 const { last } = require('../components/identifier')
 const { getPropertyModifiers } = require('../components/property')
+const { configuration } = require('../config')
 
 /** @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').resolver.TypeResolveOptions} TypeResolveOptions */
 /** @typedef {import('../typedefs').visitor.Inflection} Inflection */
 /** @typedef {{typeName: string, typeInfo: TypeResolveInfo & { inflection: Inflection }}} ResolveAndRequireInfo */
 
@@ -30,7 +32,7 @@ class Resolver {
         this.visitor = visitor
 
         /** @type {BuiltinResolver} */
-        this.builtinResolver = new BuiltinResolver(visitor.options)
+        this.builtinResolver = new BuiltinResolver({ IEEE754Compatible: configuration.IEEE754Compatible })
 
         /** @type {Library[]} */
         this.libraries = [new Library(require.resolve('../../library/cds.hana.ts'))]
@@ -63,8 +65,7 @@ class Resolver {
      * @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'))
+        return type.items ? !type.items.notNull : !type.notNull
     }
 
     /**
@@ -159,8 +160,8 @@ class Resolver {
         if (parts.length <= 1) return []
 
         /**
-         * @param {string} property
-         * @param {import('../typedefs').resolver.EntityCSN} entity
+         * @param {string} property - the property to check
+         * @param {import('../typedefs').resolver.EntityCSN} entity - the entity to check the property against
          */
         const isPropertyOf = (property, entity) => property && Object.hasOwn(entity?.elements ?? {}, property)
 
@@ -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
@@ -385,6 +387,10 @@ class Resolver {
             plural: typeName
         }
 
+        if (element.key === true) {
+            typeName = createKey(typeName)
+        }
+
         // FIXME: typeName could probably just become part of typeInfo
         return { typeName, typeInfo }
     }
@@ -430,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
@@ -501,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) {
@@ -525,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
@@ -99,47 +132,13 @@ export module resolver {
 
 export module util {
     export type Annotations = {
-        name?: string,
+        name: string,
         '@singular'?: string,
         '@plural'?: string
     }
-
-    export type CommandLineFlags = {
-        desc: string,
-        default?: any
-    }
-
-    export type ParsedFlag = {
-        positional: string[],
-        named: { [key: string]: any }
-    }
 }
 
 export module visitor {
-    export type CompileParameters = {
-        outputDirectory: string,
-        logLevel: number,
-        useEntitiesProxy: boolean,
-        jsConfigPath?: string,
-        inlineDeclarations: 'flat' | 'structured',
-        propertiesOptional: boolean,
-        IEEE754Compatible: boolean,
-    }
-
-    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',
-        /**
-         * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects
-         */
-        useEntitiesProxy: boolean
-    }
-
     export type Inflection = {
         typeName?: string,
         singular: string,
@@ -158,9 +157,54 @@ export module visitor {
     }
 }
 
+export module config {
+    export module cli {
+        export type CLIFlags = 'version' | 'help'
+        export type ParameterSchema = {
+            [key: string]: {
+                desc: string,
+                allowed?: string[],
+                allowedHint?: string,
+                type?: 'string' | 'boolean' | 'number',
+                default?: string,
+                defaultHint?: string,
+                postprocess?: (value: string) => any,
+                camel?: string,
+                snake?: string
+            }
+        }
+
+        export type ParsedParameters = {
+            positional: string[],
+            named: { [key: keyof RuntimeParameters]: {
+                value: any,
+                isDefault: boolean,
+            } }
+        }
+    }
+
+    export type Configuration = {
+        outputDirectory: string,
+        logLevel: number,
+        /**
+         * `useEntitiesProxy = true` will wrap the `module.exports.<entityName>` in `Proxy` objects
+         */
+        useEntitiesProxy: boolean,
+        jsConfigPath?: string,
+        /**
+         * `inlineDeclarations = 'structured'` -> @see {@link inline.StructuredInlineDeclarationResolver}
+         * `inlineDeclarations = 'flat'` -> @see {@link inline.FlatInlineDeclarationResolver}
+         */
+        inlineDeclarations: 'flat' | 'structured',
+        /** `propertiesOptional = true` -> all properties are generated as optional ?:. (standard CAP behaviour, where properties be unavailable) */
+        propertiesOptional: boolean,
+        /**
+         * `IEEE754Compatible = true` -> any cds.Decimal will become `number | string`
+         */
+        IEEE754Compatible: boolean
+    }
+}
+
 export module file {
     export type Namespace = Object<string, Buffer>
-    export type FileOptions = {
-        useEntitiesProxy: boolean
-    }
 }

package/lib/util.js

@@ -19,6 +19,16 @@ const annotations = {
     plural: ['@plural'],
 }
 
+/**
+ * Converts a camelCase string to snake_case.
+ * @param {string} camel - The camelCase string.
+ * @returns {string} - The snake_case string.
+ */
+const camelToSnake = camel => camel
+    .replace(/([a-z])([A-Z])/g, '$1_$2') // Handle camelCase
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2') // Handle sequences of uppercase letters
+    .toLowerCase()
+
 /**
  * Tries to retrieve an annotation that specifies the singular name
  * from a CSN. Valid annotations are listed in util.annotations
@@ -27,6 +37,7 @@ const annotations = {
  * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the singular annotation or undefined
  */
+// @ts-expect-error - can not use possible undefined from find as key
 const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.hasOwn(csn, a))]
 
 /**
@@ -37,6 +48,7 @@ const getSingularAnnotation = csn => csn[annotations.singular.find(a => Object.h
  * @param {EntityCSN} csn - the CSN of an entity to check
  * @returns {string | undefined} the plural annotation or undefined
  */
+// @ts-expect-error - can not use possible undefined from find as key
 const getPluralAnnotation = csn => csn[annotations.plural.find(a => Object.hasOwn(csn, a))]
 
 /**
@@ -62,9 +74,9 @@ const unlocalize = name => {
  * @param {boolean?} stripped - if true, leading namespace will be stripped
  */
 const singular4 = (dn, stripped = false) => {
-    let n = dn.name || dn
+    let n = dn.name ?? dn
     if (stripped) {
-        n = n.match(last)[0]
+        n = n.match(last)?.[0] ?? ''
     }
     return (
         getSingularAnnotation(dn) ??
@@ -94,9 +106,9 @@ const singular4 = (dn, stripped = false) => {
  * @param {boolean} stripped - if true, leading namespace will be stripped
  */
 const plural4 = (dn, stripped) => {
-    let n = dn.name || dn
+    let n = dn.name ?? dn
     if (stripped) {
-        n = n.match(last)[0]
+        n = n.match(last)?.[0]
     }
     return (
         getPluralAnnotation(dn) ??
@@ -123,72 +135,13 @@ const deepMerge = (target, source) => {
     Object.assign(target, source)
 }
 
-/**
- * Parses command line arguments into named and positional parameters.
- * 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
- * from their definition in validFlags.
- * @param {string[]} argv - list of command line arguments
- * @param {{[key: string]: CommandlineFlag}} validFlags - allowed flags. May specify default values.
- * @returns {ParsedFlags}
- */
-const parseCommandlineArgs = (argv, validFlags) => {
-    const isFlag = (/** @type {string} */ arg) => arg.startsWith('--')
-    const positional = []
-    const named = {}
-
-    let i = 0
-    while (i < argv.length) {
-        let arg = argv[i]
-        if (isFlag(arg)) {
-            arg = arg.slice(2)
-            if (!(arg in validFlags)) {
-                throw new Error(`invalid named flag '${arg}'`)
-            } else {
-                const next = argv[i + 1]
-                if (next && !isFlag(next)) {
-                    named[arg] = next
-                    i++
-                } else {
-                    named[arg] = validFlags[arg].default
-                }
-
-                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 ${(allowedHint ?? allowed.join(', '))}`)
-                }
-            }
-        } else {
-            positional.push(arg)
-        }
-        i++
-    }
-
-    const defaults = Object.entries(validFlags)
-        .filter(e => !!e[1].default)
-        .reduce((dict, [k, v]) => {
-            dict[k] = v.default
-            return dict
-        }, {})
-
-    return {
-        named: Object.assign(defaults, named),
-        positional,
-    }
-}
-
 module.exports = {
     annotations,
+    camelToSnake,
     getSingularAnnotation,
     getPluralAnnotation,
     unlocalize,
     singular4,
     plural4,
-    parseCommandlineArgs,
     deepMerge
 }