@sap/cds-dk 10.0.3 → 10.0.4

package/node_modules/@cap-js/db-service/lib/infer/join-tree.js

@@ -0,0 +1,278 @@
+'use strict'
+
+const { prettyPrintRef } = require('../utils')
+
+// REVISIT: define following unknown types
+
+/**
+ * @typedef {unknown} $refLink
+ */
+
+/**
+ * @typedef {unknown} parent
+ */
+
+/**
+ * @typedef {unknown} where
+ */
+
+/**
+ * @typedef {unknown} children
+ */
+
+/**
+ * @typedef {unknown} queryArtifact
+ */
+
+/**
+ * @typedef {string} alias
+ */
+
+/**
+ * @typedef {Map<alias,Root>} _roots
+ */
+
+/**
+ * @typedef {Object.<string, unknown>} sources
+ */
+
+/**
+ * A class representing a Node in the join tree.
+ */
+class Node {
+  /**
+   * @param {$refLink} $refLink
+   * @param {parent} parent
+   * @param {where} where
+   */
+  constructor($refLink, parent, where = null, args = null) {
+    /** @type {$refLink} - A reference link to this node. */
+    this.$refLink = $refLink
+    /** @type {parent} - The parent Node of this node. */
+    this.parent = parent
+    /** @type {where} - An optional condition to be applied to this node. */
+    this.where = where
+    /** @type {args} - optional parameter object to be applied to this node. */
+    const targetHasParams = $refLink.definition._target?.params || $refLink.definition._target?.['@cds.persistence.udf']
+    if (!args && targetHasParams) args = {} // if no args are provided, provide empty argument list
+    this.args = args
+    /** @type {children} - A Map of children nodes belonging to this node. */
+    this.children = new Map()
+  }
+}
+
+/**
+ * A class representing the root of the join tree.
+ */
+class Root {
+  /**
+   * @param {[alias, queryArtifact]} querySource
+   */
+  constructor(querySource) {
+    let [alias, { definition, args }] = querySource
+    /** @type {queryArtifact} - The artifact used to make the query. */
+    this.queryArtifact = definition
+    /** @type {args} - optional parameter object to be applied to this node. */
+    const definitionHasParams = definition.params || definition['@cds.persistence.udf']
+    if (!args && definitionHasParams) args = {} // if no args are provided, provide empty argument list
+    this.args = args
+    /** @type {alias} - The alias of the artifact. */
+    this.alias = alias
+    /** @type {parent} - The parent Node of this root, null for the root Node. */
+    this.parent = null
+    /** @type {children} - A Map of children nodes belonging to this root. */
+    this.children = new Map()
+  }
+}
+
+/**
+ * A class representing a Join Tree.
+ */
+class JoinTree {
+  /**
+   *
+   * @param {sources} sources
+   */
+  constructor(sources) {
+    /** @type {_roots} - A Map of root nodes. */
+    this._roots = new Map()
+    /** @type {boolean} - A boolean indicating if the join tree is in its initial state. */
+    this.isInitial = true
+    /**
+     * A map that holds query aliases which are used during the
+     * association to join translation. It is also considered during the
+     * where exists expansion.
+     *
+     * The table aliases are treated case insensitive. The index of each
+     * table alias entry, is the capitalized version of the alias.
+     * @type {Map<string, string>}
+     */
+    this._queryAliases = new Map()
+    Object.entries(sources).forEach(entry => {
+      const alias = this.addNextAvailableTableAlias(entry[0])
+      this._roots.set(alias, new Root(entry))
+    })
+  }
+
+  /**
+   * Recursively adds aliases of subqueries from a given query source to the alias map.
+   *
+   * @param {object} sources - The sources of the inferred subquery in a FROM clause.
+   */
+  addAliasesOfSubqueryInFrom(sources) {
+    Object.entries(sources).forEach(e => {
+      this.addNextAvailableTableAlias(e[0])
+      if (e[1].sources)
+        // recurse
+        this.addAliasesOfSubqueryInFrom(e[1].sources)
+    })
+  }
+
+  /**
+   * Calculates and adds the next available table alias to the alias map.
+   *
+   * @param {string} alias - The original alias name.
+   * @param {unknown[]} outerQueries - An array of outer queries.
+   * @param {string} key - The key to be used for storing the alias in the map. If not provided, the upper-case version of the alias will be used as the key.
+   * @returns {string} - The next unambiguous table alias.
+   */
+  addNextAvailableTableAlias(alias, outerQueries, key) {
+    const upperAlias = alias.toUpperCase()
+    if (this._queryAliases.get(upperAlias) || outerQueries?.some(outer => outerHasAlias(outer, key))) {
+      let j = 2
+      while (this._queryAliases.get(upperAlias + j) || outerQueries?.some(outer => outerHasAlias(outer, key, j))) j += 1
+      alias += j
+    }
+    this._queryAliases.set(key || alias.toUpperCase(), alias)
+    return alias
+
+    function outerHasAlias(outer, searchInValues = false, number) {
+      const currAlias = number ? upperAlias + number : upperAlias
+      return searchInValues ? Array.from(outer.joinTree._queryAliases.values()).includes(currAlias) : outer.joinTree._queryAliases.get(currAlias)
+    }
+  }
+
+  /**
+   * Merges a column into the join tree.
+   *
+   * It begins by inferring the source of the given column, which is the table alias where the column is resolvable.
+   * Each step during this process represents a node in the join tree. If a node already exists in the tree, the current step is replaced by the already merged node.
+   * If not, it creates a new Node and ensures proper aliasing and foreign key access.
+   *
+   * @param {object} col - The column object to be merged into the existing join tree. This object should have the properties $refLinks and ref.
+   * @returns {boolean} - Always returns true, indicating the column has been successfully merged into the join tree.
+   */
+  mergeColumn(col, outerQueries = null) {
+    if (this.isInitial) this.isInitial = false
+    const head = col.$refLinks[0]
+    let node = this._roots.get(head.alias)
+    let i = 0
+    if (!node) {
+      this._roots.forEach(r => {
+        // find the correct query source
+        if (
+          r.queryArtifact === head.target ||
+          r.queryArtifact === head.target._target /** might as well be a query for order by */
+        )
+          node = r
+      })
+    } else {
+      i += 1 // skip first step which is table alias
+    }
+
+    // if no root node was found, the column is selected from a subquery
+    if (!node) return
+    while (i < col.ref.length) {
+      if(col.join === 'inner') node.join = 'inner'
+      const step = col.ref[i]
+      const { where, args } = step
+      const id = joinId(step, args, where)
+      const next = node.children.get(id)
+      const $refLink = col.$refLinks[i]
+      // sanity check: error out if we can't produce a join
+      if ($refLink.definition.keys && $refLink.definition.keys.length === 0) {
+        const path = prettyPrintRef(col.ref)
+        throw new Error(`Path step “${$refLink.alias}” of “${path}” has no foreign keys`)
+      }
+
+      if (next) {
+        // step already seen before
+        node = next
+        // re-set $refLink to equal the one which got already merged
+        col.$refLinks[i].alias = node.$refLink.alias
+        col.$refLinks[i].definition = node.$refLink.definition
+        col.$refLinks[i].target = node.$refLink.target
+        col.$refLinks[i].onlyForeignKeyAccess = node.$refLink.onlyForeignKeyAccess
+      } else {
+        if (col.expand && !col.ref[i + 1]) {
+          node.$refLink.onlyForeignKeyAccess = false
+          return true
+        }
+        const child = new Node($refLink, node, where, args)
+        if (child.$refLink.definition.isAssociation) {
+          if (child.where || child.$refLink.definition.on || col.inline) {
+            // filter is always join relevant
+            // if the column ends up in an `inline` -> each assoc step is join relevant
+            child.$refLink.onlyForeignKeyAccess = false
+            // all parents are now also join relevant
+            markParentAsJoinRelevant(child.parent)
+          } else {
+            child.$refLink.onlyForeignKeyAccess = true
+          }
+          child.$refLink.alias = this.addNextAvailableTableAlias($refLink.alias, outerQueries)
+        }
+        const elements =
+          node.$refLink?.definition.isAssociation &&
+          (node.$refLink.definition.elements || node.$refLink.definition.foreignKeys)
+        if (node.$refLink && (!elements || !(child.$refLink.definition.name in elements))) {
+          // no foreign key access
+          node.$refLink.onlyForeignKeyAccess = false
+          markParentAsJoinRelevant(node.parent)
+
+          col.$refLinks[i - 1] = node.$refLink
+        }
+
+        node.children.set(id, child)
+        node = child
+      }
+      i += 1
+    }
+    return true
+
+    function markParentAsJoinRelevant(parent) {
+      while (parent) {
+        if (parent.$refLink?.definition.isAssociation) {
+          parent.$refLink.onlyForeignKeyAccess = false
+        }
+        parent = parent.parent
+      }
+    }
+
+    function joinId(step, args, where) {
+      let appendix
+      if (where && args) appendix = JSON.stringify(where) + JSON.stringify(args)
+      else if (where) appendix = JSON.stringify(where)
+      else if (args) appendix = JSON.stringify(args)
+      return appendix ? step.id + appendix : step
+    }
+  }
+
+  /**
+   * Performs a depth-first search for the next association in the children of the given node which does not only access foreign keys.
+   *
+   * @param {Node} node - The node from which to search for the next association.
+   * @returns {Node|null} - Returns the node which represents an association or null if none was found.
+   */
+  findNextAssoc(node) {
+    if (node.$refLink.definition.isAssociation && !node.$refLink.onlyForeignKeyAccess) return node
+    // recurse on each child node
+    for (const child of node.children.values()) {
+      const grandChild = this.findNextAssoc(child)
+      if (grandChild) return grandChild
+    }
+
+    return null
+  }
+}
+
+module.exports = JoinTree

package/node_modules/@cap-js/db-service/lib/infer/pseudos.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const cds = require('@sap/cds')
+const { String, Timestamp } = cds.builtin.types
+
+const pseudos = {
+  elements: {
+    $user: {
+      elements: {
+        id: String,
+        locale: String, // deprecated
+        tenant: String, // deprecated
+      },
+    },
+    $now: Timestamp,
+    $at: Timestamp,
+    $from: Timestamp,
+    $to: Timestamp,
+    $locale: String,
+    $tenant: String,
+  },
+}
+
+module.exports = { pseudos }

package/node_modules/@cap-js/db-service/lib/search.js

@@ -0,0 +1,220 @@
+'use strict'
+
+const DRAFT_COLUMNS_UNION = {
+  IsActiveEntity: 1,
+  HasActiveEntity: 1,
+  HasDraftEntity: 1,
+  DraftAdministrativeData_DraftUUID: 1,
+  SiblingEntity: 1,
+  DraftAdministrativeData: 1,
+}
+const DEFAULT_SEARCHABLE_TYPE = 'cds.String'
+
+// only those which return strings are relevant for search
+const aggregateFunctions = {
+  MAX: true,
+  MIN: true,
+}
+
+/**
+ * This method gets all columns for an entity.
+ * It includes the generated foreign keys from managed associations, structured elements and complex and custom types.
+ * Moreover, it provides the annotations starting with '@' for each column.
+ *
+ * @param {object} entity - the csn entity
+ * @param {object} [options]
+ * @param [options.onlyNames=false] - decides if the column name or the csn representation of the column should be returned
+ * @param [options.filterDraft=false] - indicates whether the draft columns should be filtered if the entity is draft enabled
+ * @param [options.removeIgnore=false]
+ * @param [options.filterVirtual=false]
+ * @param [options.keysOnly=false]
+ * @returns {Array<object>} - array of columns
+ */
+const getColumns = (
+  entity,
+  { onlyNames = false, removeIgnore = false, filterDraft = true, filterVirtual = false, keysOnly = false },
+) => {
+  const columns = []
+  const elements = entity.elements
+
+  for (const each in elements) {
+    const element = elements[each]
+    if (filterVirtual && element.virtual) continue
+    if (removeIgnore && element['@cds.api.ignore']) continue
+    if (filterDraft && each in DRAFT_COLUMNS_UNION) continue
+    if (keysOnly && !element.key) continue
+    columns.push(onlyNames ? each : element)
+  }
+
+  return columns
+}
+
+const _isColumnCalculated = (query, columnName) => {
+  if (!query) return false
+  if (query.SELECT?.columns?.find(col => col.xpr && col.as === columnName)) return true
+  return _isColumnCalculated(query._target?.query, columnName)
+}
+
+const _getSearchableColumns = entity => {
+  const columnsOptions = { removeIgnore: true, filterVirtual: true }
+  const columns = entity.SELECT?.columns || getColumns(entity, columnsOptions)
+  const cdsSearchTerm = '@cds.search'
+  const cdsSearchKeys = []
+  const cdsSearchColumnMap = new Map()
+
+  for (const key in entity) {
+    if (key.startsWith(cdsSearchTerm)) cdsSearchKeys.push(key)
+  }
+
+  let skipDefaultSearchableElements = false
+  const deepSearchCandidates = []
+
+  // build a map of columns annotated with the @cds.search annotation
+  for (const key of cdsSearchKeys) {
+    const columnName = key.split(cdsSearchTerm + '.').pop()
+    const annotationKey = `${cdsSearchTerm}.${columnName}`
+    const annotationValue = entity[annotationKey]
+
+    const column = entity.elements[columnName]
+    // always ignore virtual elements from search
+    if(column?.virtual) continue
+    if (column?.isAssociation || columnName.includes('.')) {
+      if(!annotationValue)
+        continue
+
+      const ref = columnName.split('.')
+      if(ref.length > 1) skipDefaultSearchableElements = true
+      deepSearchCandidates.push({ ref })
+      continue
+    }
+
+    if(annotationValue) skipDefaultSearchableElements = true
+    cdsSearchColumnMap.set(columnName, annotationValue)
+  }
+
+  const searchableColumns = columns.filter(column => {
+    const annotatedColumnValue = cdsSearchColumnMap.get(column.name)
+    const elementName = column.as || column.ref?.at(-1) || column.name
+    const element = entity.elements[elementName]
+
+    // the element is searchable if it is annotated with the @cds.search, e.g.:
+    // `@cds.search { element1: true }` or `@cds.search { element1 }`
+    if (annotatedColumnValue) return true
+
+    // calculated elements are only searchable if requested through `@cds.search`
+    if (column.value) return false
+
+    // if at least one element is explicitly annotated as searchable, e.g.:
+    // `@cds.search { element1: true }` or `@cds.search { element1 }`
+    // and it is not the current column name, then it must be excluded from the search
+    if (skipDefaultSearchableElements) return false
+
+    // the element is considered searchable if it is explicitly annotated as such or
+    // if it is not annotated and the column is typed as a string (excluding elements/elements expressions)
+    return (
+      annotatedColumnValue === undefined &&
+      element?.type === DEFAULT_SEARCHABLE_TYPE &&
+      !_isColumnCalculated(entity?.query, column.name)
+    )
+  })
+
+  if (deepSearchCandidates.length) {
+    deepSearchCandidates.forEach(c => {
+      let element = entity
+      for (let i = 0; i < c.ref.length; ++i) {
+        const curr = c.ref[i]
+        const next = element.elements?.[curr] ?? element._target?.elements?.[curr]
+
+        if (!next) { // e.g. if a search element is not part of a projection
+          element = undefined
+          break
+        }
+
+        if (next.isAssociation && i === c.ref.length - 1) {
+          _getSearchableColumns(next._target).forEach(r => searchableColumns.push({ ref: c.ref.concat(...r.ref) }))
+        }
+
+        element = next
+      }
+
+      if (element?.type === DEFAULT_SEARCHABLE_TYPE) {
+        searchableColumns.push({ ref: c.ref })
+      }
+    })
+  }
+
+  return searchableColumns.map(column => {
+    if (column.ref) return column
+    return { ref: [column.name] }
+  })
+}
+
+/**
+ * @returns {Array<object>} - array of columns
+ */
+const computeColumnsToBeSearched = (cqn, entity = { __searchableColumns: [] }) => {
+  let toBeSearched = []
+
+  // aggregations case
+  // in the new parser groupBy is moved to sub select.
+  if (cqn._aggregated || /* new parser */ cqn.SELECT.groupBy || cqn.SELECT?.from?.SELECT?.groupBy) {
+    cqn.SELECT.columns?.forEach(column => {
+      const elementName = column.as || column.ref?.at(-1) || column.name
+      const element = cqn.elements[elementName]
+      if (column.func || column.xpr) {
+        // exclude $count by SELECT of number of Items in a Collection
+        if (
+          cqn.SELECT.columns.length === 1 &&
+          column.func === 'count' &&
+          (column.as === '_counted_' || column.as === '$count')
+        ) {
+          return
+        }
+
+        // only strings can be searched
+        if (element?.type !== DEFAULT_SEARCHABLE_TYPE) {
+          if (column.xpr) return
+          if (column.func && !(column.func.toUpperCase() in aggregateFunctions)) return
+        }
+
+        const searchTerm = {}
+        if (column.func) {
+          searchTerm.func = column.func
+          searchTerm.args = column.args
+        } else if (column.xpr) {
+          searchTerm.xpr = column.xpr
+        }
+        toBeSearched.push(searchTerm)
+        return
+      }
+
+      // no need to set ref[0] to alias, because columns were already properly transformed
+      if (column.ref) {
+        if (element?.type !== DEFAULT_SEARCHABLE_TYPE) return
+        column = { ref: [...column.ref] }
+        toBeSearched.push(column)
+        return
+      }
+    })
+  } else {
+    if (entity.kind === 'entity') {
+      // first check cache
+      toBeSearched =
+        entity.own('__searchableColumns') || entity.set('__searchableColumns', _getSearchableColumns(entity))
+    } else {
+      // if we search on a subquery, we don't have a cache
+      toBeSearched = _getSearchableColumns(entity)
+    }
+    toBeSearched = toBeSearched.map(c => {
+      const column = { ref: [...c.ref] }
+      return column
+    })
+  }
+
+  return toBeSearched
+}
+
+module.exports = {
+  getColumns,
+  computeColumnsToBeSearched,
+}

package/node_modules/@cap-js/db-service/lib/utils.js

@@ -0,0 +1,177 @@
+'use strict'
+
+const cds = require('@sap/cds')
+
+/**
+ * Formats a ref array into a string representation.
+ * If the first step is an entity, the separator is a colon, otherwise a dot.
+ *
+ * @param {Array} ref - The reference array to be formatted.
+ * @param {Object} model - The model object containing definitions.
+ * @returns {string} The formatted string representation of the reference.
+ */
+function prettyPrintRef(ref, model = null) {
+  return ref.reduce((acc, curr, j) => {
+    if (j > 0) {
+      if (j === 1 && model?.definitions[ref[0]]?.kind === 'entity') {
+        acc += ':'
+      } else {
+        acc += '.'
+      }
+    }
+    return acc + `${curr.id ? curr.id + '[…]' : curr}`
+  }, '')
+}
+
+function hasOwnSkip(definition) {
+  return (
+    definition && Object.hasOwn(definition, '@cds.persistence.skip') && definition['@cds.persistence.skip'] === true
+  )
+}
+
+function isRuntimeView(definition) {
+  if (!definition || !cds.env.features.runtime_views) return false
+  if (definition['_isRuntimeView']) return true
+  if (!definition['@cds.persistence.skip']) {
+    Object.defineProperty(definition, '_isRuntimeView', {
+      value: true,
+      writable: false,
+      configurable: true,
+      enumerable: false
+    })
+    return true
+  }
+  // views with "as select from" variant are also runtime views, even if they are annotated with persistence skip
+  if (definition.query && !definition.query._target) return true
+  if (definition.query) return isRuntimeView(definition.query._target)
+
+  return false
+}
+
+/**
+ * Determines if a definition is calculated on read.
+ * - Stored calculated elements are not unfolded
+ * - Association like calculated elements have been re-written by the compiler
+ *   they essentially behave like unmanaged associations as their calculations
+ *   have been incorporated into an on-condition which is handled elsewhere
+ *
+ * @param {Object} def - The definition to check.
+ * @returns {boolean} - Returns true if the definition is calculated on read, otherwise false.
+ */
+function isCalculatedOnRead(def) {
+  return isCalculatedElement(def) && !def.value.stored && !def.on
+}
+function isCalculatedElement(def) {
+  return def?.value
+}
+
+/**
+ * Calculates the implicit table alias for a given string.
+ *
+ * Based on the last part of the string, the implicit alias is calculated
+ * by taking the first character and prepending it with '$'.
+ * A leading '$' is removed if the last part already starts with '$'.
+ *
+ * @example
+ * getImplicitAlias('Books') => '$B'
+ * getImplicitAlias('bookshop.Books') => '$B'
+ * getImplicitAlias('bookshop.$B') => '$B'
+ *
+ * @param {string} str - The input string.
+ * @returns {string}
+ */
+function getImplicitAlias(str, useTechnicalAlias = true) {
+  const index = str.lastIndexOf('.')
+  if (useTechnicalAlias) {
+    const postfix = (index != -1 ? str.substring(index + 1) : str).replace(/^\$/, '')[0] || /* str === '$' */ '$'
+    return '$' + postfix
+  }
+  return index != -1 ? str.substring(index + 1) : str
+}
+
+function defineProperty(obj, prop, value) {
+  return Object.defineProperty(obj, prop, {
+    value,
+    writable: true,
+    configurable: true,
+  })
+}
+
+/**
+ * Shared utility functions which operate dynamically on the model / query.
+ *
+ * @param {CSN.model} model
+ * @param {CQL} query
+ */
+function getModelUtils(model, query) {
+  /**
+   * Returns the name of the localized entity for the given `definition`.
+   * 
+   * If the query is `localized`, returns the name of the `localized` version of the `definition`.
+   * If there is no `localized` version of the `definition`, return the name of the `definition`
+   *
+   * @param {CSN.definition} definition
+   * @returns the name of the localized entity for the given `definition` or `definition.name`
+   */
+  function getLocalizedName(definition) {
+    if (!isLocalized(definition)) return definition.name
+    const view = getDefinition(`localized.${definition.name}`)
+    return view?.name || definition.name
+  }
+
+  /**
+   * Returns true if the definition shall be localized, in the context of the given query.
+   * 
+   * If a given query is required to be translated, the query has
+   * the `.localized` property set to `true`. If that is the case,
+   * and the definition has not set the `@cds.localized` annotation
+   * to `false`, the given definition must be translated.
+   *
+   * @returns true if the given definition shall be localized
+   */
+  function isLocalized(definition) {
+    return (
+      query.SELECT?.localized &&
+      definition?.['@cds.localized'] !== false &&
+      !query.SELECT.forUpdate &&
+      !query.SELECT.forShareLock
+    )
+  }
+
+  /**
+   * Returns the (potentially localized) CSN definition for the given name from the model.
+   *
+   * @param {string} name - The name of the definition to retrieve.
+   * @returns {Object|null} The CSN definition or null if not found. The definition may be localized.
+   */
+  function getDefinition(name) {
+    if (!name) return null
+    const def = model.definitions[name]
+    if (!def || !isLocalized(def)) return def
+    return model.definitions[`localized.${def.name}`] || def
+  }
+  return {
+    getLocalizedName,
+    isLocalized,
+    getDefinition,
+  }
+}
+
+function resolveTable(target) {
+  if (target.query?._target && !Object.prototype.hasOwnProperty.call(target, '@cds.persistence.table'))
+    return resolveTable(target.query._target)
+  return target
+}
+
+// export the function to be used in other modules
+module.exports = {
+  prettyPrintRef,
+  isCalculatedOnRead,
+  isCalculatedElement,
+  getImplicitAlias,
+  defineProperty,
+  getModelUtils,
+  hasOwnSkip,
+  isRuntimeView,
+  resolveTable
+}