@cap-js/cds-typer 0.22.0 → 0.23.0

package/lib/file.js

@@ -10,7 +10,7 @@ const { createObjectOf } = require('./components/wrappers')
 
 const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not change its contents manually!'
 
-/** @typedef {import('./typedefs').file.Namespace} Namespace */ 
+/** @typedef {import('./typedefs').file.Namespace} Namespace */
 
 class File {
     /**
@@ -20,7 +20,7 @@ class File {
     toTypeDefs() { return '' }
 
     /**
-     * Concats the classnames to an export dictionary 
+     * Concats the classnames to an export dictionary
      * to create the accompanying JS file for the typings.
      * @returns {string} a string containing the module.exports for the JS file.
      */
@@ -32,7 +32,7 @@ class File {
  * For example, the cap.hana types are included in a separate predefined library file
  * which is only included if the model that is being compiled references any of these types.
  * A library is uniquely identified by the namespace it represents. That namespace is directly
- * derived from the file's name. i.e. path/to/file/cap.hana.ts will be considered to hold 
+ * derived from the file's name. i.e. path/to/file/cap.hana.ts will be considered to hold
  * definitions describing the namespace "cap.hana".
  * These files are supposed to contain fully usable types, not CSN or a CDS file, as they are just
  * being copied verbatim when they are being used.
@@ -57,19 +57,19 @@ class Library extends File {
          * @type {string[]}
          */
         this.entities = Array.from(this.contents.matchAll(/export class (\w+)/g), ([,m]) => m)
-        
+
         /**
          * Namespace (a.b.c.d)
          * @type {string}
          */
         this.namespace = path.basename(file, '.ts')
-        
+
         /**
          * Whether this library was referenced at least once
          * @type {boolean}
          */
         this.referenced = false
-        
+
         /**
          * The Path for this library file, which is constructed from its namespace.
          * @type {Path}
@@ -80,7 +80,7 @@ class Library extends File {
     /**
      * Whether this library offers an entity of a given type (fully qualified).
      * @param {string} entity - the entity's name, e.g. cap.hana.TINYINT
-     * @returns {boolean} true, iff the namespace inferred from the passed string matches that of this library 
+     * @returns {boolean} true, iff the namespace inferred from the passed string matches that of this library
      *          and this library contains a class of that name. i.e.:
      *          ```js
      *          new Library('cap.hana.ts').offers('cap.hana.TINYINT') // -> true`
@@ -96,7 +96,7 @@ class Library extends File {
  */
 class SourceFile extends File {
     /**
-     * @param {string | Path} path 
+     * @param {string | Path} path - path to the file
      */
     constructor(path) {
         super()
@@ -107,7 +107,7 @@ class SourceFile extends File {
         /** @type {Buffer} */
         this.preamble = new Buffer()
         /** @type {{ buffer: Buffer, fqs: {name: string, fq: string}[]}} */
-        this.events = { buffer: new Buffer(), fqs: []} 
+        this.events = { buffer: new Buffer(), fqs: []}
         /** @type {Buffer} */
         this.types = new Buffer()
         /** @type {{ buffer: Buffer, data: {kvs: [string[]], name: string, fq: string, property?: string}[]}} */
@@ -144,7 +144,7 @@ class SourceFile extends File {
      * 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, ...  }
      * ```
-     * 
+     *
      * The generated string will not be just the signature of the function. Instead, it will be an object offering a callable signature.
      * 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
@@ -177,7 +177,7 @@ class SourceFile extends File {
      * aliases in the index.js file.
      * @param {string} singular - singular type without namespace.
      * @param {string} plural - plural type without namespace
-     * @param {string} original - original entity name without namespace. 
+     * @param {string} original - original entity name without namespace.
      *        In many cases this will be the same as plural.
      */
     addInflection(singular, plural, original) {
@@ -189,7 +189,7 @@ class SourceFile extends File {
      * @param {string} name - name of the function
      * @param {{relative: string | undefined, local: boolean, posix: boolean}} parameters - list of parameters, passed as [name, type] pairs
      * @param {string} returns - the return type of the function
-     * @param {'function' | 'action'} kind
+     * @param {'function' | 'action'} kind - kind of the node
      */
     addOperation(name, parameters, returns, kind) {
         //this.operations.buffer.add("// operation")
@@ -223,11 +223,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?} property - property to which the enum is attached.
+     * @param {string?} _property - property to which the enum is attached.
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
      */
-    addEnum(fq, name, kvs, property) {
+    addEnum(fq, name, kvs, _property) {
         this.enums.data.push({ name, fq, kvs })
         printEnum(this.enums.buffer, name, kvs)
     }
@@ -236,7 +236,7 @@ class SourceFile extends File {
      * Adds an inline enum to this file.
      * @param {string} entityCleanName - name of the entity the enum is attached to without namespace
      * @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} propertyName - property to which the enum is attached.
      * @param {[string, string][]} kvs - list of key-value pairs
      *  If given, the enum is considered to be an inline definition of an enum.
      *  If not, it is considered to be regular, named enum.
@@ -262,7 +262,7 @@ class SourceFile extends File {
      * ```
      */
     addInlineEnum(entityCleanName, entityFqName, propertyName, kvs) {
-        this.enums.data.push({ 
+        this.enums.data.push({
             name: `${entityCleanName}.${propertyName}`,
             property: propertyName,
             kvs,
@@ -272,11 +272,11 @@ class SourceFile extends File {
     }
 
     /**
-     * Adds a class to this file. 
+     * Adds a class to this file.
      * This differs from writing to the classes buffer,
-     * as it is just a cache to collect all classes that 
-     * are supposed to be present in this file. 
-     * @param {string} clean - cleaned name of the class 
+     * as it is just a cache to collect all classes that
+     * are supposed to be present in this file.
+     * @param {string} clean - cleaned name of the class
      * @param {string} fq - fully qualified name, including the namespace
      */
     addClass(clean, fq) {
@@ -285,7 +285,7 @@ class SourceFile extends File {
 
     /**
      * Adds an event to this file.
-     * are supposed to be present in this file. 
+     * are supposed to be present in this file.
      * @param {string} name - cleaned name of the event
      * @param {string} fq - fully qualified name, including the namespace
      */
@@ -368,7 +368,7 @@ class SourceFile extends File {
             this.preamble.join(),
             this.services.buffer.join(), // must be the very first
             this.types.join(),
-            this.enums.buffer.join(), 
+            this.enums.buffer.join(),
             this.inlineEnums.buffer.join(), // needs to be before classes
             this.aspects.join(), // needs to be before classes
             this.classes.join(),
@@ -398,7 +398,11 @@ class SourceFile extends File {
                     // 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) {
-                        exports.push(`module.exports.${original} = { is_singular: true, __proto__: csn.${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} }`
+                        exports.push(`module.exports.${original} = ${rhs}`)
                     }
                     return exports
                 })
@@ -419,7 +423,7 @@ class SourceFile extends File {
 class Buffer {
 
     /**
-     * @param {string} indentation
+     * @param {string} indentation - indentation to use (two spaces by default)
      */
     constructor(indentation = '  ') {
         /**
@@ -471,7 +475,7 @@ class Buffer {
 
     /**
      * Adds an element to the buffer with the current indentation level.
-     * @param {string} part 
+     * @param {string} part  - what to attach to the buffer
      */
     add(part) {
         this.parts.push(this.currentIndent + part)
@@ -479,7 +483,7 @@ class Buffer {
 
     /**
      * Adds an element to the buffer with one level of indent.
-     * @param {string | (() => void)} part - either a string or a function. If it is a string, it is added to the buffer. 
+     * @param {string | (() => void)} part - either a string or a function. If it is a string, it is added to the buffer.
      * If not, it is expected to be a function that manipulates the buffer as a side effect.
      */
     addIndented(part) {
@@ -528,7 +532,7 @@ class Path {
 
     /**
      * Transfoms the Path into a directory path.
-     * @param {object} params
+     * @param {object} params - parameters
      * @param {string?} params.relative - if defined, the path is constructed relative to this directory
      * @param {boolean} params.local - if set to true, './' is prefixed to the directory
      * @param {boolean} params.posix - if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
@@ -565,7 +569,7 @@ class Path {
     }
 
     /**
-     * @param {string} relative
+     * @param {string} relative - directory to which we check relatively
      * @returns {boolean} true, iff the Path refers to the current working directory, aka './'
      */
     isCwd(relative = undefined) {
@@ -579,8 +583,8 @@ class FileRepository {
     #files = {}
 
     /**
-     * @param {string} name
-     * @param {SourceFile} file 
+     * @param {string} name - file name
+     * @param {SourceFile} file - the file
      */
     add(name, file) {
         this.#files[name] = file

package/lib/logging.js

@@ -1,74 +1,16 @@
-/** @enum {number} */
-const Levels = {
-    TRACE: 1,
-    DEBUG: 2,
-    INFO: 3,
-    WARNING: 4,
-    ERROR: 8,
-    CRITICAL: 16,
-    NONE: 32,
-}
-
-class Logger {
-    constructor() {
-        this.mask = 0
-        const lvls = Object.keys(Levels)
-        for (let i = 0; i < lvls.length - 1; i++) {
-            // -1 to ignore NONE
-            const level = lvls[i]
-            this[level.toLowerCase()] = function (message) { this._log(level, message) }.bind(this)
-        }
-    }
-
-    // only temporarily to disable those warnings...
-    //warning(s) {}; error(s) {}; info(s) {}; debug(s) {};
-
-    /**
-     * Add all log levels starting at level.
-     * @param {number} baseLevel - level to start from.
-     */
-    addFrom(baseLevel) {
-        const vals = Object.values(Levels)
-        const highest = vals[vals.length - 1]
-        for (let l = Math.log2(baseLevel); Math.pow(2, l) <= highest; l++) {
-            this.add(Math.pow(2, l))
-        }
-    }
+const cds = require('@sap/cds')
 
-    /**
-     * Adds a log level to react to.
-     * @param {number} level - the level to react to. 
-     */
-    add(level) {
-        this.mask = this.mask | level
-    }
-
-    /**
-     *  Ignores a log level.
-     * @param {number} level - the level to ignore.
-     */
-    ignore(level) {
-        this.mask = this.mask ^ level
-    }
-
-    /**
-     * Attempts to log a message.
-     * Only iff levelName is a valid log level
-     * and the corresponding number if part of mask,
-     * the message gets logged.
-     * @param {Levels} levelName - name of the log level.
-     * @param {string} message - message to log.
-     */
-    _log(levelName, message) {
-        const level = Levels[levelName]
-        if (level && (this.mask & level) === level) {
-            // eslint-disable-next-line no-console
-            console.log(`[${levelName}]`, message)
-        }
-    }
-}
+const _keyFor = value => Object.entries(cds.log.levels).find(([,val]) => val === value)?.[0]
 
+// workaround until retroactively setting log level to 0 is possible
+cds.log('cds-typer', _keyFor(cds.log.levels.SILENT))
 module.exports = {
-    Levels,
-    Logger,
+    _keyFor,
+    setLevel: level => { cds.log('cds-typer', level) },
+    deprecated: {
+        WARNING: 'WARN',
+        CRITICAL: 'ERROR',
+        NONE: 'SILENT'
+    },
+    get LOG () { return cds.log('cds-typer') }
 }

package/lib/resolution/builtin.js

@@ -0,0 +1,64 @@
+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'
+    }
+
+    /**
+     * @param {object} options - additional resolution options
+     * @param {boolean} options.IEEE754Compatible - if true, the Decimal, DecimalFloat, Float, and Double types are also allowed to be strings
+     */
+    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
+    }
+}
+
+module.exports = {
+    BuiltinResolver
+}

package/lib/resolution/entity.js

@@ -0,0 +1,155 @@
+class EntityInfo {
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * Path(['n1', 'n2'])
+     * ```
+     * @type {Path}
+     */
+    namespace
+
+    // FIXME: check if scope can actually be more than one entity deep
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * ['A']
+     * ```
+     * @type {string[]}
+     */
+    scope
+
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * 'B'
+     * ```
+     * @type {string}
+     */
+    entityName
+
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * ['p', 'q']
+     * ```
+     * @type {string[]}
+     */
+    propertyAccess
+
+    /** @type {{singular: string, plural: string}} */
+    #inflection
+
+    /** @type {import('./resolver').Resolver} */
+    #resolver
+
+    /** @type {EntityRepository} */
+    #repository
+
+    /** @type {EntityInfo} */
+    #parent
+
+    /** @type {import('../typedefs').resolver.EntityCSN} */
+    #csn
+
+    get csn () {
+        return this.#csn ??= this.#resolver.csn.definitions[this.fullyQualifiedName]
+    }
+
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * { singular: B, plural: Bs }
+     * ```
+     */
+    get inflection () {
+        if (!this.#inflection) {
+            const dummyTypeInfo = {
+                plainName: this.entityName,
+                csn: this.csn,
+                isInlineDeclaration: false
+            }
+            const { singular, plural } = this.#resolver.inflect(dummyTypeInfo, this.namespace)
+            this.#inflection = { singular, plural }
+        }
+        return this.#inflection
+    }
+
+    /**
+     * @example
+     * ```ts
+     * 'n1.n2.A.B.p.q'
+     * // v
+     * 'A.B.p.q'
+     * ```
+     * @type {string}
+     */
+    get withoutNamespace () {
+        return [this.scope, this.entityName, this.propertyAccess].flat().join('.')
+    }
+
+    /**
+     * @returns {EntityInfo | null}
+     */
+    get parent () {
+        if (this.#parent !== undefined) return this.#parent
+        const parentFq = [this.namespace, this.scope].flat().join('.')
+        return this.#parent = this.#repository.getByFq(parentFq)
+    }
+
+    /**
+     * @param {string} fullyQualifiedName - the fully qualified name of the entity
+     * @param {EntityRepository} repository - the repository this info is stored in
+     * @param {import('./resolver').Resolver} resolver - the resolver
+     */
+    constructor (fullyQualifiedName, repository, resolver) {
+        const untangled = resolver.untangle(fullyQualifiedName)
+        this.#repository = repository
+        this.#resolver = resolver
+        this.fullyQualifiedName = fullyQualifiedName
+        this.namespace = untangled.namespace
+        this.scope = untangled.scope
+        this.entityName = untangled.name
+        this.propertyAccess = untangled.property
+    }
+}
+
+class EntityRepository {
+    /** @type {{ [key: string]: EntityInfo }} */
+    #cache = {}
+
+    /** @type {import('./resolver').Resolver} */
+    #resolver
+
+    /**
+     * @param {string} fq - fully qualified name of the entity
+     * @returns {EntityInfo | null}
+     */
+    getByFq (fq) {
+        if (this.#cache[fq] !== undefined) return this.#cache[fq]
+        this.#cache[fq] = this.#resolver.isPartOfModel(fq)
+            ? new EntityInfo(fq, this, this.#resolver)
+            : null
+        return this.#cache[fq]
+    }
+
+    /**
+     * @param {import('./resolver').Resolver} resolver - the resolver
+     */
+    constructor (resolver) {
+        this.#resolver = resolver
+    }
+}
+
+module.exports = {
+    EntityRepository
+}