@cap-js/cds-typer 0.23.0 → 0.25.0

package/lib/csn.js

@@ -1,31 +1,65 @@
 const annotation = '@odata.draft.enabled'
 
+/** @typedef {import('./typedefs').resolver.CSN} CSN */
+/** @typedef {import('./typedefs').resolver.EntityCSN} EntityCSN */
+/** @typedef {import('./typedefs').resolver.ProjectionCSN} ProjectionCSN */
+/** @typedef {import('./typedefs').resolver.ViewCSN} ViewCSN */
+
 /**
  * FIXME: this is pretty handwavey: we are looking for view-entities,
  * i.e. ones that have a query, but are not a cds level projection.
  * Those are still not expanded and we have to retrieve their definition
  * with all properties from the inferred model.
  * @param {any} entity - the entity
+ * @returns {entity is ViewCSN}
  */
 const isView = entity => entity.query && !entity.projection
 
+/**
+ * @param {EntityCSN} entity - the entity
+ * @returns {entity is ProjectionCSN | ViewCSN}
+ */
+const isViewOrProjection = entity => Object.hasOwn(entity, 'query') || Object.hasOwn(entity, 'projection')
+
+/**
+ * @param {EntityCSN | ProjectionCSN} entity - the entity
+ * @returns {entity is ProjectionCSN}
+ */
 const isProjection = entity => entity.projection
 
 /**
- * @param {any} entity - the entity
+ * @param {EntityCSN} entity - the entity
  * @see isView
  * Unresolved entities have to be looked up from inferred csn.
  */
 const isUnresolved = entity => entity._unresolved === true
 
+/**
+ * @param {EntityCSN} entity - the entity
+ */
 const isCsnAny = entity => entity?.constructor?.name === 'any'
 
+/**
+ * @param {EntityCSN} entity - the entity
+ */
 const isDraftEnabled = entity => entity['@odata.draft.enabled'] === true
 
+/**
+ * @param {EntityCSN} entity - the entity
+ */
 const isType = entity => entity?.kind === 'type'
 
+/**
+ * @param {EntityCSN} entity - the entity
+ */
 const isEntity = entity => entity?.kind === 'entity'
 
+/**
+ * @param {EntityCSN | undefined} entity - the entity
+ * @returns {entity is import("./typedefs").resolver.EnumCSN}
+ */
+const isEnum = entity => Boolean(entity && Object.hasOwn(entity, 'enum'))
+
 /**
  * Attempts to retrieve the max cardinality of a CSN for an entity.
  * @param {EntityCSN} element - csn of entity to retrieve cardinality for
@@ -34,13 +68,24 @@ const isEntity = entity => entity?.kind === 'entity'
  * If it is set to '*', result is Infinity.
  */
 const getMaxCardinality = element => {
-    const cardinality = element?.cardinality?.max ?? 1
+    const cardinality = element?.cardinality?.max ?? '1'
     return cardinality === '*' ? Infinity : parseInt(cardinality)
 }
 
-const getViewTarget = entity => entity.query?.SELECT?.from?.ref?.[0]
+/**
+ * @param {EntityCSN} entity - the entity
+ */
+const getViewTarget = entity => isView(entity)
+    ? entity.query?.SELECT?.from?.ref?.[0]
+    : undefined
 
-const getProjectionTarget = entity => entity.projection?.from?.ref?.[0]
+/**
+ * @param {EntityCSN} entity - the entity
+ * @returns {string | undefined}
+ */
+const getProjectionTarget = entity => isProjection(entity)
+    ? entity.projection?.from?.ref?.[0]
+    : undefined
 
 class DraftUnroller {
     /** @type {Set<string>} */
@@ -48,15 +93,18 @@ class DraftUnroller {
     /** @type {{[key: string]: boolean}} */
     #draftable = {}
     /** @type {{[key: string]: string}} */
-    #projections
-    /** @type {object[]} */
-    #entities
+    #projections = {}
+    /** @type {EntityCSN[]} */
+    #entities = []
+    /** @type {CSN | undefined} */
     #csn
     set csn(c) {
         this.#csn = c
+        if (c === undefined) return
         this.#entities = Object.values(c.definitions)
         this.#projections = this.#entities.reduce((pjs, entity) => {
             if (isProjection(entity)) {
+                // @ts-ignore - we know that entity is a projection here
                 pjs[entity.name] = getProjectionTarget(entity)
             }
             return pjs
@@ -65,11 +113,13 @@ class DraftUnroller {
     get csn() { return this.#csn }
 
     /**
-     * @param {object | string} entity - entity to set draftable annotation for.
+     * @param {EntityCSN | string} entityOrFq - entity to set draftable annotation for.
      * @param {boolean} value - whether the entity is draftable.
      */
-    #setDraftable(entity, value) {
-        if (typeof entity === 'string') entity = this.#getDefinition(entity)
+    #setDraftable(entityOrFq, value) {
+        const entity = typeof entityOrFq === 'string'
+            ? this.#getDefinition(entityOrFq)
+            : entityOrFq
         if (!entity) return  // inline definition -- not found in definitions
         entity[annotation] = value
         this.#draftable[entity.name] = value
@@ -81,32 +131,38 @@ class DraftUnroller {
     }
 
     /**
-     * @param {object | string} entityOrName - entity to look draftability up for.
+     * @param {EntityCSN | string} entityOrFq - entity to look draftability up for.
      * @returns {boolean}
      */
-    #getDraftable(entityOrName) {
-        const entity = (typeof entityOrName === 'string')
-            ? this.#getDefinition(entityOrName)
-            : entityOrName
+    #getDraftable(entityOrFq) {
+        const entity = typeof entityOrFq === 'string'
+            ? this.#getDefinition(entityOrFq)
+            : entityOrFq
         // assert(typeof entity !== 'string')
-        const name = entity?.name ?? entityOrName
+        const name = entity?.name ?? entityOrFq
+        // @ts-expect-error - .name not being present means entityOrFq is a string, so name is always a string and therefore a valid index
         return this.#draftable[name] ??= this.#propagateInheritance(entity)
     }
 
     /**
+     * FIXME: could use EntityRepository here
      * @param {string} name - name of the entity.
+     * @returns {EntityCSN}
      */
-    #getDefinition(name) { return this.csn.definitions[name] }
+    // @ts-expect-error - poor man's #getDefinitionOrThrow. We are always sure name is a valid key
+    #getDefinition(name) { return this.csn?.definitions[name] }
 
     /**
      * Propagate draft annotations through inheritance (includes).
      * The latest annotation through the inheritance chain "wins".
      * Annotations on the entity itself are always queued last, so they will always be decisive over ancestors.
-     * @param {object} entity - entity to pull draftability from its parents.
+     * @param {EntityCSN | undefined} entity - entity to pull draftability from its parents.
      */
     #propagateInheritance(entity) {
-        const annotations = (entity?.includes ?? []).map(parent => this.#getDraftable(parent))
-        annotations.push(entity?.[annotation])
+        if (!entity) return
+        /** @type {(boolean | undefined)[]} */
+        const annotations = (entity.includes ?? []).map(parent => this.#getDraftable(parent))
+        annotations.push(entity[annotation])
         this.#setDraftable(entity, annotations.filter(a => a !== undefined).at(-1) ?? false)
     }
 
@@ -114,6 +170,10 @@ class DraftUnroller {
      * Propagate draft-enablement through projections.
      */
     #propagateProjections() {
+        /**
+         * @param {string} from - entity to propagate draftability from.
+         * @param {string} to - entity to propagate draftability to.
+         */
         const propagate = (from, to) => {
             do {
                 this.#setDraftable(to, this.#getDraftable(to) || this.#getDraftable(from))
@@ -131,7 +191,7 @@ class DraftUnroller {
     /**
      * If an entity E is draftable and contains any composition of entities,
      * then those entities also become draftable. Recursively.
-     * @param {object} entity - entity to propagate all compositions from.
+     * @param {EntityCSN} entity - entity to propagate all compositions from.
      */
     #propagateCompositions(entity) {
         if (!this.#getDraftable(entity)) return
@@ -146,6 +206,7 @@ class DraftUnroller {
         }
     }
 
+    /** @param {CSN} csn - the full csn  */
     unroll(csn) {
         this.csn = csn
 
@@ -241,7 +302,7 @@ function propagateForeignKeys(csn) {
                 // foreign key fields from Associations/ Compositions.
                 if (!Object.hasOwn(this, '__keys')) {
                     const ownKeys = Object.entries(this.elements ?? {}).filter(([,el]) => el.key === true)
-                    const inheritedKeys = this.includes?.flatMap(parent => Object.entries(csn.definitions[parent].keys)) ?? []
+                    const inheritedKeys = this.includes?.flatMap((/** @type {string} */ parent) => Object.entries(csn.definitions[parent].keys)) ?? []
                     // not sure why, but .associations contains both Associations, as well as Compositions in CSN.
                     // (.compositions contains only Compositions, if any)
                     const remoteKeys = Object.entries(this.associations ?? {})
@@ -249,9 +310,7 @@ function propagateForeignKeys(csn) {
                         .flatMap(([kname, key]) => Object.entries(csn.definitions[key.target].keys)
                             .map(([ckname, ckey]) => [`${kname}_${ckname}`, ckey]))
 
-                    this.__keys = Object.fromEntries(ownKeys
-                        .concat(inheritedKeys)
-                        .concat(remoteKeys)
+                    this.__keys = Object.fromEntries([...ownKeys, ...inheritedKeys, ...remoteKeys]
                         .filter(([,ckey]) => !ckey.target)  // discard keys that are Associations. Those are already part of .elements
                     )
                 }
@@ -270,8 +329,11 @@ function amendCSN(csn) {
     propagateForeignKeys(csn)
 }
 
-
+/**
+ * @param {EntityCSN} entity - the entity
+ */
 const getProjectionAliases = entity => {
+    /** @type {Record<string, string[]>} */
     const aliases = {}
     let all = false
     for (const col of entity?.projection?.columns ?? []) {
@@ -290,8 +352,10 @@ module.exports = {
     amendCSN,
     isView,
     isProjection,
+    isViewOrProjection,
     isDraftEnabled,
     isEntity,
+    isEnum,
     isUnresolved,
     isType,
     getMaxCardinality,

package/lib/file.js

@@ -13,6 +13,13 @@ const AUTO_GEN_NOTE = '// This is an automatically generated file. Please do not
 /** @typedef {import('./typedefs').file.Namespace} Namespace */
 
 class File {
+    /**
+     * The Path for this library file, which is constructed from its namespace.
+     * @type {Path}
+     */
+    // @ts-expect-error - not initialised, but will be done in subclasses (can't make File abstract in JS)
+    path
+
     /**
      * Creates one string from the buffers representing the type definitions.
      * @returns {string} complete file contents.
@@ -42,6 +49,9 @@ class Library extends File {
         return this.contents
     }
 
+    /**
+     * @param {string} file - path to the file
+     */
     constructor(file) {
         super()
         this.contents = readFileSync(file, 'utf-8')
@@ -102,7 +112,7 @@ class SourceFile extends File {
         super()
         /** @type {Path} */
         this.path = path instanceof Path ? path : new Path(path.split('.'))
-        /** @type {object} */
+        /** @type {{[key:string]: any}} */
         this.imports = {}
         /** @type {Buffer} */
         this.preamble = new Buffer()
@@ -110,7 +120,7 @@ class SourceFile extends File {
         this.events = { buffer: new Buffer(), fqs: []}
         /** @type {Buffer} */
         this.types = new Buffer()
-        /** @type {{ buffer: Buffer, data: {kvs: [string[]], name: string, fq: string, property?: string}[]}} */
+        /** @type {{ buffer: Buffer, data: {kvs: [string, string][], name: string, fq: string, property?: string}[]}} */
         this.enums = { buffer: new Buffer(), data: [] }
         /** @type {{ buffer: Buffer }} */
         this.inlineEnums = { buffer: new Buffer() }
@@ -134,8 +144,14 @@ class SourceFile extends File {
 
     /**
      * Stringifies a lambda expression.
-     * @param {{name: string, parameters: [string, string][], returns: string, initialiser: string}} param - name, parameters, return type, and initialiser expression
-     * @returns {string} - the stringified lambda
+     * @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 {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
+     * @returns {string} the stringified lambda
      * @example
      * ```js
      * // note: these samples are actually simplified! See below.
@@ -187,7 +203,7 @@ 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 {{relative: string | undefined, local: boolean, posix: boolean}} parameters - list of parameters, passed as [name, type] pairs
+     * @param {[string, string][]} parameters - list of parameters, passed as [name, type] pairs
      * @param {string} returns - the return type of the function
      * @param {'function' | 'action'} kind - kind of the node
      */
@@ -223,11 +239,8 @@ 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.
-     *  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) {
         this.enums.data.push({ name, fq, kvs })
         printEnum(this.enums.buffer, name, kvs)
     }
@@ -318,10 +331,14 @@ class SourceFile extends File {
      * @param {string} fq - fully qualified name of the enum
      * @param {string} clean - local name of the enum
      * @param {string} rhs - the right hand side of the assignment
+     * @param {boolean} exportValueLevel - whether to export the value level of the type (relevant to enums)
      */
-    addType(fq, clean, rhs) {
+    addType(fq, clean, rhs, exportValueLevel = false) {
         this.typeNames[clean] = fq
         this.types.add(`export type ${clean} = ${rhs};`)
+        if (exportValueLevel) {
+            this.types.add(`export const ${clean} = ${rhs};`)
+        }
     }
 
     /**
@@ -438,6 +455,10 @@ class Buffer {
          * @type {string}
          */
         this.currentIndent = ''
+        /**
+         * @type {boolean}
+         */
+        this.closed = false
     }
 
     /**
@@ -483,7 +504,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 | 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) {
@@ -492,14 +513,16 @@ class Buffer {
             part()
         } else if (Array.isArray(part)) {
             part.forEach(p => { this.add(p) })
+        } else if (typeof part === 'string') {
+            this.add(part)
         }
         this.outdent()
     }
 
     /**
-     * Adds an element to a buffer with one level of indent and and opener and closer surrounding it.
+     * Adds an element to a buffer with one level of indent and opener and closer surrounding it.
      * @param {string} opener - the string to put before the indent
-     * @param {string} content - the content to indent (see {@link addIndented})
+     * @param {string | string[] | (() => void)} content - the content to indent (see {@link addIndented})
      * @param {string} closer - the string to put after the indent
      */
     addIndentedBlock(opener, content, closer) {
@@ -518,7 +541,7 @@ class Path {
      * @param {string[]} parts - parts of the path. 'a.b.c' -> ['a', 'b', 'c']
      * @param {string} kind - FIXME: currently unused
      */
-    constructor(parts, kind) {
+    constructor(parts, kind = '') {
         this.parts = parts
         this.kind = kind
     }
@@ -533,9 +556,9 @@ class Path {
     /**
      * Transfoms the Path into a directory path.
      * @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
+     * @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
      * @returns {string} directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
      */
     asDirectory(params = {}) {
@@ -569,7 +592,7 @@ class Path {
     }
 
     /**
-     * @param {string} relative - directory to which we check relatively
+     * @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) {
@@ -580,6 +603,7 @@ class Path {
 // TODO: having the repository pattern in place we can separate (some of) the printing logic from the visitor.
 // Most of it hinges primarily on resolving specific files. We can now pass the repository and the resolver to a printer.
 class FileRepository {
+    /** @type {{[key:string]: SourceFile}} */
     #files = {}
 
     /**
@@ -628,7 +652,7 @@ const writeout = async (root, sources) =>
                     fs.writeFile(path.join(dir, 'index.js'), source.toJSExports()),
                 ])
 
-            } catch (err) {
+            } catch (/** @type {any} **/err) {
                 // eslint-disable-next-line no-console
                 console.error(`Could not create parent directory ${dir}: ${err}.`)
                 // eslint-disable-next-line no-console

package/lib/logging.js

@@ -1,12 +1,16 @@
 const cds = require('@sap/cds')
 
+/** @param {string} value - the value */
+// @ts-expect-error - yes, cds.log.levels exists...
 const _keyFor = value => Object.entries(cds.log.levels).find(([,val]) => val === value)?.[0]
 
 // workaround until retroactively setting log level to 0 is possible
+// @ts-expect-error - yes, cds.log.levels exists...
 cds.log('cds-typer', _keyFor(cds.log.levels.SILENT))
 module.exports = {
     _keyFor,
-    setLevel: level => { cds.log('cds-typer', level) },
+    setLevel: (/** @type {string | number} */ level) => { cds.log('cds-typer', level) },
+    /** @type {Record<string, string>} */
     deprecated: {
         WARNING: 'WARN',
         CRITICAL: 'ERROR',

package/lib/resolution/builtin.js

@@ -2,6 +2,7 @@ class BuiltinResolver {
     /**
      * Builtin types defined by CDS.
      */
+    /** @type {Record<string, string>} */
     #builtins = {
         UUID: 'string',
         String: 'string',
@@ -32,7 +33,7 @@ class BuiltinResolver {
 
     /**
      * @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
+     * @param {boolean} [options.IEEE754Compatible] - if true, the Decimal, DecimalFloat, Float, and Double types are also allowed to be strings
      */
     constructor ({ IEEE754Compatible } = {}) {
         if (IEEE754Compatible) {
@@ -45,7 +46,7 @@ class BuiltinResolver {
     }
 
     /**
-     * @param {string | string[]} t - name or parts of the type name split on dots
+     * @param {string | string[] | import("@sap/cds").ref} 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.

package/lib/resolution/entity.js

@@ -1,3 +1,5 @@
+const { isType } = require('../csn')
+
 class EntityInfo {
     /**
      * @example
@@ -6,7 +8,7 @@ class EntityInfo {
      * // v
      * Path(['n1', 'n2'])
      * ```
-     * @type {Path}
+     * @type {import('../file').Path}
      */
     namespace
 
@@ -44,7 +46,7 @@ class EntityInfo {
      */
     propertyAccess
 
-    /** @type {{singular: string, plural: string}} */
+    /** @type {{singular: string, plural: string} | undefined} */
     #inflection
 
     /** @type {import('./resolver').Resolver} */
@@ -53,10 +55,10 @@ class EntityInfo {
     /** @type {EntityRepository} */
     #repository
 
-    /** @type {EntityInfo} */
-    #parent
+    /** @type {EntityInfo | null} */
+    #parent = null
 
-    /** @type {import('../typedefs').resolver.EntityCSN} */
+    /** @type {import('../typedefs').resolver.EntityCSN | undefined} */
     #csn
 
     get csn () {
@@ -124,7 +126,7 @@ class EntityInfo {
 }
 
 class EntityRepository {
-    /** @type {{ [key: string]: EntityInfo }} */
+    /** @type {{ [key: string]: EntityInfo | null }} */
     #cache = {}
 
     /** @type {import('./resolver').Resolver} */
@@ -142,6 +144,19 @@ class EntityRepository {
         return this.#cache[fq]
     }
 
+    /**
+     * Convenience for getByFq when you are 100% sure the entity exists.
+     * Serves to eliminate cumbersome null-handling where you know it's not necessary.
+     * For example when fq is derived from a reference to another entity.
+     * @param {string} fq - fully qualified name of the entity
+     * @returns {EntityInfo}
+     */
+    getByFqOrThrow(fq) {
+        const entityInfo = this.getByFq(fq)
+        if (entityInfo === null) throw new Error(`Entity with fq "${fq}" is not part of the model`)
+        return entityInfo
+    }
+
     /**
      * @param {import('./resolver').Resolver} resolver - the resolver
      */
@@ -150,6 +165,30 @@ class EntityRepository {
     }
 }
 
+/**
+ * Derives an identifier from an entity info.
+ * That identifier can be used to refer to a specific entity within an index.ts file.
+ * By passing a relative file, the identifier will be preceeded with a scope if needed.
+ * @param {object} options - the options
+ * @param {EntityInfo} options.info - the entity info
+ * @param {function(string): string} [options.wrapper] - a function to wrap the identifier
+ * @param {import('../file').Path} [options.relative] - the path to resolve the identifier relative to
+ * @returns {string} the identifier
+ */
+function asIdentifier ({info, wrapper = undefined, relative = undefined}) {
+    const name = isType(info.csn)
+        ? info.entityName
+        : info.inflection.singular
+
+    const wrapped = typeof wrapper === 'function'
+        ? wrapper(name)
+        : name
+    return !relative || relative.isCwd(info.namespace.asDirectory())
+        ? wrapped
+        : `${info.namespace.asIdentifier()}.${wrapped}`
+}
+
 module.exports = {
-    EntityRepository
+    EntityRepository,
+    asIdentifier
 }