@cap-js/cds-typer 0.24.0 → 0.26.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,