@cap-js/cds-typer 0.25.0 → 0.27.0

package/lib/config.js

@@ -0,0 +1,117 @@
+const cds = require('@sap/cds')
+const { camelToSnake } = require('./util')
+
+/**
+ * Makes properties of an object accessible in both camelCase and snake_case.
+ * Snake_case gets precedence over camelCase.
+ * @template T
+ * @param {T} target - The object to proxy.
+ * @returns {T} - The proxied object.
+ */
+const camelSnakeHybrid = target => {
+    // @ts-expect-error - expecting target to be of type {}, which is not T (same for following)
+    const proxy = new Proxy(target, {
+        get(target, prop) {
+            // @ts-expect-error
+            return target[camelToSnake(prop)] ?? target[prop]
+        },
+        set(target, p, v) {
+            // @ts-expect-error
+            target[camelToSnake(p)] = v
+            return true
+        }
+    })
+    // need to make sure all properties are initially available in snake_case
+    // @ts-expect-error
+    for (const [k,v] of Object.entries(target)) {
+        // @ts-expect-error
+        proxy[k] = v
+    }
+    // @ts-expect-error
+    return proxy
+}
+class Config {
+    static #defaults = {
+        propertiesOptional: true,
+        useEntitiesProxy: false,
+        inlineDeclarations: 'flat'
+    }
+
+    values = undefined
+    proxy = undefined
+
+    init () {
+        this.values = {...Config.#defaults, ...(cds.env.typer ?? {})}
+        this.proxy = camelSnakeHybrid(this.values)
+    }
+
+    constructor() {
+        // proxy around config still allows arbitrary property access:
+        // require('config').configuration.logLevel = 'warn' will work
+        // eslint-disable-next-line no-constructor-return
+        return new Proxy(this, {
+            get(target, prop) {
+                // lazy loading of cds.env
+                // if we don't do this, configuration will load cds.env whenever it is
+                // first imported anywhere (even by proxy from, say, cli.js).
+                // So we don't get to modify cds.env before that, which is important
+                // in cds-build.js.
+                // FIXME: revisit. This is horrible.
+                if (target.values === undefined) target.init()
+                return target[prop] ?? target.proxy[prop]
+            },
+            set(target, p, v) {
+                if (target.values === undefined) target.init()
+
+                // this.value, this.proxy etc should not be forwarded to the wrapped values
+                if (target[p]) {
+                    target[p] = v
+                } else {
+                    target.proxy[p] = v
+                }
+                return true
+            }
+        })
+    }
+
+    /**
+     * @param {string} key - The key to set.
+     * @param {any} value - The value to set
+     */
+    setOne (key, value) {
+        this.proxy[key] = value
+    }
+
+    /**
+     * @param {object} props - The properties to set.
+     */
+    setMany (props) {
+        for (const [k,v] of Object.entries(props)) {
+            this.proxy[k] = v
+        }
+    }
+
+    /**
+     * Resets the config value and sets all its values from another passed
+     * config object. This allows to keep the reference to the same object.
+     * @param {Config} config - Another config object to set all config entries from.
+     */
+    setFrom (config) {
+        this.values = camelSnakeHybrid({})
+        this.setMany(config.values)
+    }
+
+    clone () {
+        const res = new Config()
+        res.init()
+        res.setMany(this.values)
+        return res
+    }
+}
+
+module.exports = {
+    camelSnakeHybrid,
+    /** @type {import('./typedefs').config.Configuration} */
+    // @ts-ignore
+    configuration: new Config()
+}

package/lib/file.js

@@ -6,7 +6,9 @@ const { readFileSync } = require('fs')
 const { printEnum, propertyToInlineEnumName, stringifyEnumImplementation } = require('./components/enum')
 const { normalise } = require('./components/identifier')
 const { empty } = require('./components/typescript')
+const { proxyAccessFunction } = require('./components/javascript')
 const { createObjectOf } = require('./components/wrappers')
+const { configuration } = require('./config')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
@@ -140,50 +142,64 @@ class SourceFile extends File {
         this.inflections = []
         /** @type {{ buffer: Buffer, names: string[]}} */
         this.services = { buffer: new Buffer(), names: [] }
+        /** @type {Record<string,string[]>} */
+        this.entityProxies = {}
     }
 
     /**
      * Stringifies a lambda expression.
      * @param {object} options - options
      * @param {string} options.name - name of the lambda
-     * @param {[string, string][]} [options.parameters] - list of parameters, passed as [name, type] pairs
+     * @param {import('./typedefs').visitor.ParamInfo[]} [options.parameters] - list of parameters, passed as [name, modifier, type, doc] pairs
      * @param {string} [options.returns] - the return type of the function
      * @param {'action' | 'function'} options.kind - kind of the lambda
      * @param {string} [options.initialiser] - the initialiser expression
      * @param {boolean} [options.isStatic] - whether the lambda is static
+     * @param {{positional?: boolean, named?: boolean}} [options.callStyles] - whether to generate positional and/or named call styles
+     * @param {string[]?} [options.doc] - documentation for the operation
      * @returns {string} the stringified lambda
      * @example
      * ```js
      * // note: these samples are actually simplified! See below.
-     * stringifyLambda({parameters: [['p','T']]})  // f: { (p: T): any, ... }
-     * stringifyLambda({name: 'f', parameters: [['p','T']]})  // f: { (p: T) => any, ...  }
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // f: { (p: T) => number, ...  }
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number', initialiser: '_ => 42'})  // f: { (p: T): string = _ => 42, ...  }
+     * stringifyLambda({parameters: [['p','','T']]})  // f: { (p: T): any, ... }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}]})  // f: { (p: T) => any, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',modifier:'?',type:'T',doc:'/** doc *\/'}], returns: 'number'})  // /** doc *\/f?: { (p: T) => number, ...  }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number', initialiser: '_ => 42'})  // f?: { (p: T): string = _ => 42, ...  }
      * ```
      *
-     * The generated string will not be just the signature of the function. Instead, it will be an object offering a callable signature.
+     * The generated string will not be just the signature of the function. Instead, it will be an object offering callable signature(s).
      * On top of that, it will also expose a property `__parameters`, which is an object reflecting the functions parameters.
      * The reason for this is that the CDS runtime actually treats the function parameters as a named object. This can not be rectified via
      * type magic, as parameter names do not exist on type level. So we can not use these names to reuse them as object properties.
      * Instead, we generate this utility object for the runtime to use:
      * @example
      * ```js
-     * stringifyLambda({name: 'f', parameters: [['p','T']], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
+     * stringifyLambda({name: 'f', parameters: [{name:'p',type:'T'}], returns: 'number'})  // { (p: T): number, __parameters: { p: T } }
      * ```
      */
-    static stringifyLambda({name, parameters=[], returns='any', initialiser, isStatic=false, kind}) {
-        const parameterTypes = parameters.map(([n, t]) => `${normalise(n)}: ${t}`).join(', ')
+    static stringifyLambda({name, parameters=[], returns='any', kind, initialiser, isStatic=false, callStyles={positional:true, named:true}, doc}) {
+        let docStr = doc?.length ? doc.join('\n')+'\n' : ''
+        const parameterTypes = parameters.map(({name, modifier, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}${modifier}: ${type}`).join(', ')
         const parameterTypeAsObject = parameterTypes.length
             ? createObjectOf(parameterTypes)
             : empty
-        const callableSignature = `(${parameterTypes}): ${returns}`
+        const callableSignatures = []
+        if (callStyles.positional) {
+            const paramTypesPositional = parameters.map(({name, type, doc}) => `${doc?'\n'+doc:''}${normalise(name)}: ${type}`).join(', ') // must not include ? modifiers
+            callableSignatures.push(`// positional\n${docStr}(${paramTypesPositional}): ${returns}`) // docs shows up on action consumer side: `.action(...)`
+        }
+        if (callStyles.named) {
+            const parameterNames = createObjectOf(parameters.map(({name}) => normalise(name)).join(', '))
+            callableSignatures.push(`// named\n${docStr}(${parameterNames}: ${parameterTypeAsObject}): ${returns}`)
+        }
+        if (callableSignatures.length === 0) throw new Error('At least one call style must be specified')
         let prefix = name ? `${normalise(name)}: `: ''
         if (prefix && isStatic) {
             prefix = `static ${prefix}`
         }
         const kindDef = kind ? `, kind: '${kind}'` : ''
         const suffix = initialiser ? ` = ${initialiser}` : ''
-        const lambda = `{ ${callableSignature}, __parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
+        const lambda = `{\n${callableSignatures.join('\n')}, \n// metadata (do not use)\n__parameters: ${parameterTypeAsObject}, __returns: ${returns}${kindDef}}`
         return prefix + lambda + suffix
     }
 
@@ -203,13 +219,16 @@ class SourceFile extends File {
     /**
      * Adds a function definition in form of a arrow function to the file.
      * @param {string} name - name of the function
-     * @param {[string, string][]} parameters - list of parameters, passed as [name, type] pairs
+     * @param {import('./typedefs').visitor.ParamInfo[]} parameters - list of parameters, passed as [name, modifier, type] tuple
      * @param {string} returns - the return type of the function
      * @param {'function' | 'action'} kind - kind of the node
+     * @param {string[]} doc - documentation for the function
+     * @param {{positional?: boolean, named?: boolean}} callStyles - how the operation can be called
      */
-    addOperation(name, parameters, returns, kind) {
-        //this.operations.buffer.add("// operation")
-        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind})};`)
+    addOperation(name, parameters, returns, kind, doc, callStyles) {
+        // this.operations.buffer.add(`// ${kind}`)
+        if (doc) this.operations.buffer.add(doc.join('\n')) // docs shows up on action provider side: `.on(action,...)`
+        this.operations.buffer.add(`export declare const ${SourceFile.stringifyLambda({name, parameters, returns, kind, doc, callStyles})};`)
         this.operations.names.push(name)
     }
 
@@ -239,10 +258,11 @@ class SourceFile extends File {
      * @param {string} fq - fully qualified name of the enum (entity name within CSN)
      * @param {string} name - local name of the enum
      * @param {[string, string][]} kvs - list of key-value pairs
+     * @param {string[]} doc - the enum docs
      */
-    addEnum(fq, name, kvs) {
+    addEnum(fq, name, kvs, doc) {
         this.enums.data.push({ name, fq, kvs })
-        printEnum(this.enums.buffer, name, kvs)
+        printEnum(this.enums.buffer, name, kvs, {}, doc)
     }
 
     /**
@@ -251,6 +271,7 @@ class SourceFile extends File {
      * @param {string} entityFqName - name of the entity the enum is attached to with namespace
      * @param {string} propertyName - property to which the enum is attached.
      * @param {[string, string][]} kvs - list of key-value pairs
+     * @param {string[]} doc - the enum docs
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
      * @example
@@ -274,14 +295,16 @@ class SourceFile extends File {
      * }
      * ```
      */
-    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs) {
+    addInlineEnum(entityCleanName, entityFqName, propertyName, kvs, doc=[]) {
         this.enums.data.push({
             name: `${entityCleanName}.${propertyName}`,
             property: propertyName,
             kvs,
             fq: `${entityCleanName}.${propertyName}`
         })
-        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false})
+        const entityProxy = this.entityProxies[entityCleanName] ?? (this.entityProxies[entityCleanName] = [])
+        entityProxy.push(propertyName)
+        printEnum(this.inlineEnums.buffer, propertyToInlineEnumName(entityCleanName, propertyName), kvs, {export: false}, doc)
     }
 
     /**
@@ -363,11 +386,16 @@ class SourceFile extends File {
      */
     getImports() {
         const buffer = new Buffer()
+        if (this.services.names.length) {
+            // currently only needed to extend cds.Service and would trigger unused-variable-errors in strict configs
+            buffer.add('import cds from \'@sap/cds\'') // TODO should go to visitor#printService, but can't express this as Path
+        }
         for (const imp of Object.values(this.imports)) {
             if (!imp.isCwd(this.path.asDirectory())) {
                 buffer.add(`import * as ${imp.asIdentifier()} from '${imp.asDirectory({relative: this.path.asDirectory()})}';`)
             }
         }
+        buffer.add('') // empty line after imports
         return buffer
     }
 
@@ -394,31 +422,92 @@ class SourceFile extends File {
             namespaces.join()  // needs to be after classes for possible declaration merging
         ].filter(Boolean).join('\n')
     }
+    #getEntityProxyFunctionExport() {
+        return `module.exports.createEntityProxy = ${proxyAccessFunction}`
+    }
+    /**
+     * Returns boilerplate code for `index.js` files
+     * - `useEntitiesProxy = true` -> import `createEntityProxy` function for entity proxy
+     * - `useEntitiesProxy = false` -> retrieve entities via `cds.entities(namespace)`
+     * @returns {string[]}
+     */
+    #getJSExportBoilerplate() {
+        const namespace = this.path.asNamespace()
 
+        const boilerplate = [AUTO_GEN_NOTE]
+        if (configuration.useEntitiesProxy) {
+            if (namespace === '_') {
+                boilerplate.push('const cds = require(\'@sap/cds\')', this.#getEntityProxyFunctionExport())
+            } else {
+                boilerplate.push(`const { createEntityProxy } = require('${new Path(['_']).asDirectory({relative: this.path.asDirectory()})}')`)
+            }
+        } else {
+            boilerplate.push(
+                'const cds = require(\'@sap/cds\')',
+                `const csn = cds.entities('${namespace}')`
+            )
+        }
+        return boilerplate
+    }
+    /**
+     * Returns RHS for entity `module.exports` assignments
+     * - `useEntitiesProxy = true` -> use function calls to create `Proxy` objects
+     * - `useEntitiesProxy = false` -> access entity from CSN directly
+     * @param {string} singular - singular name of entity
+     * @param {string} original - original name of entity
+     * @returns {{singularRhs: string, pluralRhs: string}}
+     */
+    #getEntityExportsRhs(singular, original) {
+        if (configuration.useEntitiesProxy) {
+            const namespace = this.path.asNamespace()
+            // determine the custom properties for the proxy function call
+            const customProps = this.entityProxies[singular] ?? []
+            let customPropsStr = customProps.length ? `, customProps: ${JSON.stringify(customProps)}` : ''
+
+            return {
+                singularRhs: `createEntityProxy(['${namespace}', '${original}'], { target: { is_singular: true }${customPropsStr} })`,
+                pluralRhs: `createEntityProxy(['${namespace}', '${original}'])`,
+            }
+        } else {
+            return {
+                singularRhs: `{ is_singular: true, __proto__: csn.${original} }`,
+                pluralRhs: `csn.${original}`
+            }
+        }
+    }
     toJSExports() {
-        return [AUTO_GEN_NOTE, 'const cds = require(\'@sap/cds\')', `const csn = cds.entities('${this.path.asNamespace()}')`] // boilerplate
+        return this.#getJSExportBoilerplate() // boilerplate
             .concat(
                 // FIXME: move stringification of service into own module
-                this.services.names.map(name => `module.exports = { name: '${name}' }`))  // there should be only one
+                this.services.names.flatMap(name => {
+                    const nameSimple = name.split('.').pop()
+                    return [
+                        '// service',
+                        `const ${nameSimple} = { name: '${name}' }`,
+                        `module.exports = ${nameSimple}`, // there should be only one and must be the first
+                        `module.exports.${nameSimple} = ${nameSimple}`
+                    ]
+                })
+            )
             .concat(this.inflections
             // sorting the entries based on the number of dots in their singular.
             // that makes sure we have defined all parent namespaces before adding subclasses to them e.g.:
             // "module.exports.Books" is defined before "module.exports.Books.text"
                 .sort(([a], [b]) => a.split('.').length - b.split('.').length)
                 .flatMap(([singular, plural, original]) => {
-                    const exports = [`module.exports.${singular} = { is_singular: true, __proto__: csn.${original} }`]
+                    const { singularRhs, pluralRhs } = this.#getEntityExportsRhs(singular, original)
+
+                    const exports = [`// ${original}`, `module.exports.${singular} = ${singularRhs}`]
                     if (!/Array<.*>/.test(plural) && plural !== original) {
                         // FIXME: this is a hack to support CDS types that will produce "Array<MyType>" as plural, which we do not want as export in the index.js files
-                        exports.push(`module.exports.${plural} = csn.${original}`)
+                        exports.push(`module.exports.${plural} = ${pluralRhs}`)
                     }
                     // FIXME: we currently produce at most 3 entries.
                     // This could be an issue when the user re-used the original name in a @singular/@plural annotation.
                     // Seems unlikely, but we have to eliminate the original entry if users start running into this.
                     if (singular !== original) {
                         // do not do the is_singular spiel if the original name is used for the plural
-                        const rhs = plural === original
-                            ? `csn.${original}`
-                            : `{ is_singular: true, __proto__: csn.${original} }`
+                        const rhs = plural === original ? pluralRhs : singularRhs
                         exports.push(`module.exports.${original} = ${rhs}`)
                     }
                     return exports

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,6 +13,7 @@ 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 */
@@ -30,7 +31,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'))]
@@ -58,6 +59,14 @@ 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) {
+        return !type.notNull
+    }
+
     /**
      * Returns all libraries that have been referenced at least once.
      * @returns {Library[]}
@@ -150,8 +159,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)
 
@@ -376,6 +385,10 @@ class Resolver {
             plural: typeName
         }
 
+        if (element.key === true) {
+            typeName = createKey(typeName)
+        }
+
         // FIXME: typeName could probably just become part of typeInfo
         return { typeName, typeInfo }
     }

package/lib/typedefs.d.ts

@@ -8,6 +8,7 @@ export module resolver {
 
     export type EntityCSN = {
         actions?: OperationCSN[],
+        operations?: OperationCSN[],
         cardinality?: { max?: '*' | string }
         compositions?: { target: string }[]
         doc?: string,
@@ -98,50 +99,76 @@ export module resolver {
 
 export module util {
     export type Annotations = {
-        name?: string,
+        name: string,
         '@singular'?: string,
         '@plural'?: string
     }
+}
+
+export module visitor {
+    export type Inflection = {
+        typeName?: string,
+        singular: string,
+        plural: string
+    }
 
-    export type CommandLineFlags = {
-        desc: string,
-        default?: any
+    export type Context = {
+        entity: string
     }
 
-    export type ParsedFlag = {
-        positional: string[],
-        named: { [key: string]: any }
+    export type ParamInfo = {
+        name: string,
+        modifier: '' | '?',
+        type: string,
+        doc?: string
     }
 }
 
-export module visitor {
-    export type CompileParameters = {
+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: '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',
-    }
-
-    export type Inflection = {
-        typeName?: string,
-        singular: string,
-        plural: string
-    }
-
-    export type Context = {
-        entity: string
+        /** `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
     }
 }