@cap-js/cds-typer 0.26.0 → 0.28.0

package/lib/visitor.js

@@ -2,13 +2,13 @@
 
 const util = require('./util')
 
-const { amendCSN, isView, isUnresolved, propagateForeignKeys, isDraftEnabled, isType, isProjection, getMaxCardinality, isViewOrProjection, isEnum } = require('./csn')
+const { isView, isUnresolved, propagateForeignKeys, collectDraftEnabledEntities, isDraftEnabled, isType, isProjection, getMaxCardinality, isViewOrProjection, isEnum, isEntity } = require('./csn')
 // eslint-disable-next-line no-unused-vars
 const { SourceFile, FileRepository, Buffer, Path } = require('./file')
 const { FlatInlineDeclarationResolver, StructuredInlineDeclarationResolver } = require('./components/inline')
 const { Resolver } = require('./resolution/resolver')
 const { LOG } = require('./logging')
-const { docify, createPromiseOf, createUnionOf } = require('./components/wrappers')
+const { docify, createPromiseOf, createUnionOf, createKeysOf, createElementsOf, stringIdent, createDraftsOf, createDraftOf } = require('./components/wrappers')
 const { csnToEnumPairs, propertyToInlineEnumName, isInlineEnumType, stringifyEnumType } = require('./components/enum')
 const { isReferenceType } = require('./components/reference')
 const { empty } = require('./components/typescript')
@@ -16,23 +16,17 @@ const { baseDefinitions } = require('./components/basedefs')
 const { EntityRepository, asIdentifier } = require('./resolution/entity')
 const { last } = require('./components/identifier')
 const { getPropertyModifiers } = require('./components/property')
+const { configuration } = require('./config')
+const { createMember } = require('./components/class')
 
 /** @typedef {import('./file').File} File */
 /** @typedef {import('./typedefs').visitor.Context} Context */
-/** @typedef {import('./typedefs').visitor.CompileParameters} CompileParameters */
-/** @typedef {import('./typedefs').visitor.VisitorOptions} VisitorOptions */
 /** @typedef {import('./typedefs').visitor.Inflection} Inflection */
 /** @typedef {import('./typedefs').resolver.CSN} CSN */
+/** @typedef {import('./typedefs').resolver.TypeResolveOptions} TypeResolveOptions */
 /** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
 /** @typedef {import('./typedefs').resolver.EnumCSN} EnumCSN */
 
-const defaults = {
-    // FIXME: add defaults for remaining parameters
-    propertiesOptional: true,
-    useEntitiesProxy: false,
-    inlineDeclarations: 'flat'
-}
-
 class Visitor {
     /**
      * Gathers all files that are supposed to be written to
@@ -46,12 +40,12 @@ class Visitor {
 
     /**
      * @param {{xtended: CSN, inferred: CSN}} csn - root CSN
-     * @param {VisitorOptions | {}} options - the options
      */
-    constructor(csn, options = {}) {
-        amendCSN(csn.xtended)
+    constructor(csn) {
+        propagateForeignKeys(csn.xtended)
         propagateForeignKeys(csn.inferred)
-        this.options = { ...defaults, ...options }
+        // has to be executed on the inferred model as autoexposed entities are not included in the xtended csn
+        collectDraftEnabledEntities(csn.inferred)
         this.csn = csn
 
         /** @type {Context[]} **/
@@ -64,12 +58,10 @@ class Visitor {
         this.entityRepository = new EntityRepository(this.resolver)
 
         /** @type {FileRepository} */
-        this.fileRepository = new FileRepository(this.options)
-        // REVISIT: better way to pass options to base source file ???
-        baseDefinitions.options = this.options
+        this.fileRepository = new FileRepository()
         this.fileRepository.add(baseDefinitions.path.asNamespace(), baseDefinitions)
         this.inlineDeclarationResolver =
-            this.options.inlineDeclarations === 'structured'
+            configuration.inlineDeclarations === 'structured'
                 ? new StructuredInlineDeclarationResolver(this)
                 : new FlatInlineDeclarationResolver(this)
 
@@ -105,7 +97,13 @@ class Visitor {
                 // FIXME: references to types of entity properties may be missing from xtendend flavour (see #103)
                 // this should be revisted once we settle on a single flavour.
                 const target = this.csn.xtended.definitions[targetName] ?? this.csn.inferred.definitions[targetName]
-                this.visitEntity(name, target)
+                if (target.kind !== 'type') {
+                    // skip if the target is a property, like in:
+                    // books: Association to many Author.books ...
+                    // as this would result in a type definition that
+                    // name-clashes with the actual declaration of Author
+                    this.visitEntity(name, target)
+                }
             } else {
                 LOG.error(`Expecting an autoexposed projection within a service. Skipping ${name}`)
             }
@@ -145,21 +143,58 @@ class Visitor {
             : ''
         if (actions.length) {
             buffer.addIndentedBlock(`declare static readonly actions: ${inherited}{`,
-                actions.map(([aname, action]) => SourceFile.stringifyLambda({
-                    name: aname,
-                    parameters: this.#stringifyFunctionParams(action.params, file),
-                    returns: action.returns
-                        ? this.resolver.resolveAndRequire(action.returns, file).typeName
-                        : 'any',
-                    kind: action.kind,
-                    doc: docify(action.doc)
-                })), '}'
+                () => {
+                    for (const [aname, action] of actions) {
+                        const [opener, content, closer] = SourceFile.stringifyLambda({
+                            name: aname,
+                            parameters: this.#stringifyFunctionParams(action.params, file),
+                            returns: action.returns
+                                ? this.resolver.resolveAndRequire(action.returns, file).typeName
+                                : 'any',
+                            kind: action.kind,
+                            doc: docify(action.doc)})
+                        buffer.addIndentedBlock(opener, content, closer)
+                    }
+                }, '}'
             ) // end of actions
         } else {
-            buffer.add(`declare static readonly actions: ${inherited}${empty}`)
+            buffer.add(createMember({
+                name: 'actions',
+                type: `${inherited}${empty}`,
+                isStatic: true,
+                isReadonly: true
+            }))
         }
     }
 
+    /**
+     * @param {Buffer} buffer - the buffer to write the keys into
+     * @param {string} clean - the clean name of the entity
+     */
+    #printStaticKeys(buffer, clean) {
+        buffer.add(createMember({
+            name: 'keys',
+            type: createKeysOf(clean),
+            isDeclare: true,
+            isStatic: true,
+            isReadonly: true,
+        }))
+    }
+
+    /**
+     * @param {Buffer} buffer - the buffer to write the elements into
+     * @param {string} clean - the clean name of the entity
+     */
+    #printStaticElements(buffer, clean) {
+        buffer.add(createMember({
+            name: 'elements',
+            type: createElementsOf(clean),
+            isDeclare: true,
+            isStatic: true,
+            isReadonly: true
+        }))
+    }
+
     /**
      * Transforms an entity or CDS aspect into a JS aspect (aka mixin).
      * That is, for an element A we get:
@@ -227,12 +262,15 @@ class Visitor {
             buffer.addIndentedBlock(`return class ${clean} extends ${ancestorsAspects} {`, () => {
                 /** @type {import('./typedefs').resolver.EnumCSN[]} */
                 const enums = []
-                for (let [ename, element] of Object.entries(entity.elements ?? {})) {
+                /** @type {TypeResolveOptions} */
+                const resolverOptions = { forceInlineStructs: isEntity(entity) && configuration.inlineDeclarations === 'flat'}
+
+                for (let [ename, element] of Object.entries(entity.elements ?? [])) {
                     if (element.target && /\.texts?/.test(element.target)) {
                         LOG.warn(`referring to .texts property in ${fq}. This is currently not supported and will be ignored.`)
                         continue
                     }
-                    this.visitElement(ename, element, file, buffer)
+                    this.visitElement({name: ename, element, file, buffer, resolverOptions})
 
                     // make foreign keys explicit
                     if (element.target) {
@@ -248,7 +286,7 @@ class Visitor {
                                     const kelement = Object.assign(Object.create(originalKeyElement), {
                                         isRefNotNull: !!element.notNull || !!element.key
                                     })
-                                    this.visitElement(foreignKey, kelement, file, buffer)
+                                    this.visitElement({name: foreignKey, element: kelement, file, buffer, resolverOptions})
                                 }
                             }
                         }
@@ -260,35 +298,49 @@ class Visitor {
                     }
                 }
 
-                if ('kind' in entity) {
-                    buffer.addIndented([`static readonly kind: 'entity' | 'type' | 'aspect' = '${entity.kind}';`])
+                for (const e of enums) {
+                    const eDoc = docify(e.doc)
+                    buffer.add(eDoc)
+                    buffer.add(createMember({
+                        name: e.name,
+                        initialiser: propertyToInlineEnumName(clean, e.name),
+                        isStatic: true,
+                    }))
+                    file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
                 }
 
-                buffer.addIndented(() => {
-                    for (const e of enums) {
-                        const eDoc = docify(e.doc)
-                        eDoc.forEach(d => { buffer.add(d) })
-                        buffer.add(`static ${e.name} = ${propertyToInlineEnumName(clean, e.name)}`)
-                        file.addInlineEnum(clean, fq, e.name, csnToEnumPairs(e, {unwrapVals: true}), eDoc)
-                    }
-                    this.#printStaticActions(entity, buffer, ancestorInfos, file)
-                })
+                if ('kind' in entity) {
+                    buffer.add(createMember({
+                        name: 'kind',
+                        type: '"entity" | "type" | "aspect"',
+                        isStatic: true,
+                        isReadonly: true,
+                        isDeclare: false,
+                        isOverride: ancestorInfos.some(ancestor => ancestor.csn.kind),
+                        initialiser: stringIdent(entity.kind)
+                    }))
+                }
+                this.#printStaticKeys(buffer, clean)
+                this.#printStaticElements(buffer, clean)
+                this.#printStaticActions(entity, buffer, ancestorInfos, file)
             }, '};') // end of generated class
         }, '}') // end of aspect
 
         // CLASS WITH ADDED ASPECTS
         file.addImport(baseDefinitions.path)
         docify(entity.doc).forEach(d => { buffer.add(d) })
-        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(clean, entity).join('\n')}}`)
+        buffer.add(`export class ${identSingular(clean)} extends ${identAspect(toLocalIdent({clean, fq}))}(${baseDefinitions.path.asIdentifier()}.Entity) {${this.#staticClassContents(fq, clean).join('\n')}}`)
         this.contexts.pop()
     }
 
     /**
+     * @param {string} fq - fully qualified name of the entity
      * @param {string} clean - the clean name of the entity
-     * @param {EntityCSN} entity - the entity to generate the static contents for
+     * @param {boolean} [isPlural] - `true` if passed entity is plural
      */
-    #staticClassContents(clean, entity) {
-        return isDraftEnabled(entity) ? [`static drafts: typeof ${clean}`] : []
+    #staticClassContents(fq, clean, isPlural = false) {
+        if (!isDraftEnabled(fq)) return []
+        return [`static drafts: ${isPlural ? createDraftsOf(clean) : createDraftOf(clean)}`]
     }
 
     /**
@@ -344,9 +396,6 @@ class Visitor {
             ? this.csn.inferred.definitions[fq]
             : entity
 
-        // draft enablement is stored in csn.xtended. Iff we took the entity from csn.inferred, we have to carry the draft-enablement over at this point
-        target['@odata.draft.enabled'] = isDraftEnabled(entity)
-
         this.#aspectify(fq, target, buffer, { cleanName: singular })
 
         buffer.add(overrideNameProperty(singular, entity.name))
@@ -362,13 +411,13 @@ class Visitor {
             }
             // plural can not be a type alias to $singular[] but needs to be a proper class instead,
             // so it can get passed as value to CQL functions.
-            const additionalProperties = this.#staticClassContents(singular, entity)
+            const additionalProperties = this.#staticClassContents(fq, singular, true)
             additionalProperties.push('$count?: number')
-            docify(entity.doc).forEach(d => { buffer.add(d) })
+            buffer.add(docify(entity.doc))
             buffer.add(`export class ${plural} extends Array<${singular}> {${additionalProperties.join('\n')}}`)
             buffer.add(overrideNameProperty(plural, entity.name))
         }
-        buffer.add('')
+        buffer.blankLine()
     }
 
     /**
@@ -488,12 +537,13 @@ class Visitor {
         buffer.add('// event')
         // only declare classes, as their properties are not optional, so we don't have to do awkward initialisation thereof.
         buffer.addIndentedBlock(`export declare class ${entityName} {`, () => {
-            const propOpt = this.options.propertiesOptional
-            this.options.propertiesOptional = false
+            const propOpt = configuration.propertiesOptional
+            // FIXME: shouldn't need to change config here! Idea: init Visitor with .options fed from config, then manipulate that
+            configuration.propertiesOptional = false
             for (const [ename, element] of Object.entries(event.elements ?? {})) {
-                this.visitElement(ename, element, file, buffer)
+                this.visitElement({name: ename, element, file, buffer})
             }
-            this.options.propertiesOptional = propOpt
+            configuration.propertiesOptional = propOpt
         }, '}')
     }
 
@@ -512,12 +562,12 @@ class Visitor {
         // file.addImport(new Path(['cds'], '')) TODO make sap/cds import work
         buffer.addIndentedBlock(`export class ${serviceNameSimple} extends cds.Service {`, () => {
             Object.entries(service.operations ?? {}).forEach(([name, {doc}]) => {
-                docify(doc).forEach(d => { buffer.add(d) })
+                buffer.add(docify(doc))
                 buffer.add(`declare ${name}: typeof ${name}`)
             })
         }, '}')
         buffer.add(`export default ${serviceNameSimple}`)
-        buffer.add('')
+        buffer.blankLine()
         file.addService(service.name)
     }
 
@@ -580,13 +630,15 @@ class Visitor {
 
     /**
      * Visits a single element in an entity.
-     * @param {string} name - name of the element
-     * @param {EntityCSN} element - CSN data belonging to the the element.
-     * @param {SourceFile} file - the namespace file the surrounding entity is being printed into.
-     * @param {Buffer} [buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @param {object} options - options
+     * @param {string} options.name - name of the element
+     * @param {EntityCSN} options.element - CSN data belonging to the the element.
+     * @param {SourceFile} options.file - the namespace file the surrounding entity is being printed into.
+     * @param {Buffer} [options.buffer] - buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @param {TypeResolveOptions} [options.resolverOptions] - custom type resolver options
      * @returns @see InlineDeclarationResolver.visitElement
      */
-    visitElement(name, element, file, buffer = file.classes) {
+    visitElement({name, element, file, buffer = file.classes, resolverOptions}) {
         return this.inlineDeclarationResolver.visitElement({
             name,
             element,
@@ -594,7 +646,8 @@ class Visitor {
             buffer,
             // we explicitly pass the "declare" modifier here to avoid problems with noImplicitOverride and useDefineForClassFields in strict tsconfigs
             // but not inside type defs (e.g. parameter types) where this would be a syntax error
-            modifiers: getPropertyModifiers(element)
+            modifiers: getPropertyModifiers(element),
+            resolverOptions
         })
     }
 }

package/library/cds.hana.ts

@@ -9,7 +9,7 @@ export class VARCHAR extends String {};
 export class CLOB extends String {};
 export class BINARY extends String {}
 export class ST_POINT {
-    public x: number;
-    public y: number;
+    declare public x: number;
+    declare public y: number;
 }
 export class ST_GEOMETRY { /* FIXME */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/cds-typer",
-  "version": "0.26.0",
+  "version": "0.28.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",
@@ -25,7 +25,8 @@
     "doc:prepare": "npm run doc:clean && mkdir -p doc/types",
     "doc:typegen": "./node_modules/.bin/tsc ./lib/*.js  --skipLibCheck --declaration --allowJs --emitDeclarationOnly --outDir doc/types && cd doc/types && tsc --init",
     "doc:cli": "npm run cli -- --help > ./doc/cli.txt",
-    "jsdoc:check": "tsc --noEmit --project jsconfig.json"
+    "jsdoc:check": "tsc --noEmit --project jsconfig.json",
+    "write:cds-typer-shema": "node scripts/write-cds-typer-schema.js"
   },
   "files": [
     "lib/",
@@ -60,5 +61,72 @@
       "test/smoke.jest.config.js",
       "test/unit.jest.config.js"
     ]
+  },
+  "cds": {
+    "schema": {
+      "buildTaskType": {
+        "name": "typescript",
+        "description": "TypeScript build plugin. For use after the nodejs build task."
+      },
+      "cds": {
+        "typer": {
+          "type": "object",
+          "description": "Configuration for CDS Typer",
+          "properties": {
+            "output_directory": {
+              "type": "string",
+              "description": "Root directory to write the generated files to.",
+              "default": "@cds-models"
+            },
+            "log_level": {
+              "type": "string",
+              "description": "Minimum log level that is printed.\nThe default is only used if no explicit value is passed\nand there is no configuration passed via cds.env either.",
+              "enum": [
+                "SILENT",
+                "ERROR",
+                "WARN",
+                "INFO",
+                "DEBUG",
+                "TRACE",
+                "SILLY",
+                "VERBOSE",
+                "WARNING",
+                "CRITICAL",
+                "NONE"
+              ],
+              "default": "ERROR"
+            },
+            "js_config_path": {
+              "type": "string",
+              "description": "Path to where the jsconfig.json should be written.\nIf specified, cds-typer will create a jsconfig.json file and\nset it up to restrict property usage in types entities to\nexisting properties only."
+            },
+            "use_entities_proxy": {
+              "type": "boolean",
+              "description": "If set to true the 'cds.entities' exports in the generated 'index.js'\nfiles will be wrapped in 'Proxy' objects\nso static import/require calls can be used everywhere.\n\nWARNING: entity properties can still only be accessed after\n'cds.entities' has been loaded",
+              "default": false
+            },
+            "inline_declarations": {
+              "type": "string",
+              "description": "Whether to resolve inline type declarations\nflat: (x_a, x_b, ...)\nor structured: (x: {a, b}).",
+              "enum": [
+                "flat",
+                "structured"
+              ],
+              "default": "structured"
+            },
+            "properties_optional": {
+              "type": "boolean",
+              "description": "If set to true, properties in entities are\nalways generated as optional (a?: T).",
+              "default": true
+            },
+            "ieee754compatible": {
+              "type": "boolean",
+              "description": "If set to true, floating point properties are generated\nas IEEE754 compatible '(number | string)' instead of 'number'.",
+              "default": false
+            }
+          }
+        }
+      }
+    }
   }
 }