@sap/cds 9.4.4 → 9.5.1

package/CHANGELOG.md

@@ -4,6 +4,79 @@
 - The format is based on [Keep a Changelog](https://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](https://semver.org/).
 
+## Version 9.5.1 - 2025-12-01
+
+### Fixed
+
+- Draft child creation in case `cds.features.new_draft_via_action` is enabled
+- Draft messages of declarative constraints
+- Persisted draft messages in case of on-commit errors
+- Async UCL tenant mapping for UCL SPII v2
+- Quoting in `cds.compile.to.yaml`
+
+## Version 9.5.0 - 2025-11-26
+
+### Added
+
+- Support for Declarative Constraints (`@assert`; beta)
+- Status Transition Flows (`@flow`; beta):
+  + Aspect `sap.common.FlowHistory` automatically appended to entities with a `@to: $flow.previous`
+    + Deactivate via `cds.features.history_for_flows=false`
+    + Experimental: Via `cds.features.history_for_flows='all'`, all entities with a flow definition get appended
+    + Note: FlowHistory is not maintained within drafts
+  + Support for `@flow.status: <element name>` on entity level
+  + UI annotation generation adds action to UI automatically (Object Page and List Report) but hidden in draft mode
+  + Experimental support for CRUD flows:
+    + Pseudo bound actions `CREATE` and `UPDATE` events can be flow-annotated
+      + Note: The `CREATE` event cannot have a `@from` condition
+    + Pseudo bound actions for drafts `NEW`, `EDIT`, `PATCH`, `DISCARD`, and `SAVE` can be flow-annotated
+      + Note: Flow annotations inside drafts (`@from`, `@to`) are processed as in standard flow transitions, with the following exceptions:
+        + The `NEW` event cannot have a `@from` condition
+        + The `DISCARD` event cannot have a `@to` condition
+- Support for pseudo protocols
+- Support for Async UCL tenant mapping notification flow
+- `flush` on a queued service returns a Promise that resolves when immediate work (i.e., not scheduled for future) is processed
+- For draft-enabled entities, IsActiveEntity=true can be omitted from url
+- Support for `@Common.DraftRoot.NewAction` annotation with feature flag `cds.features.new_draft_via_action`
+  + Generic collection bound action `draftNew` will be added to draft enabled entities
+  + The action specified in the annotation will be rewritten into a draft `NEW` event
+  + Active instances of draft enabled entities can be created directly via `POST`
+- Limited support for `$compute` query option: computed properties are only supported in `$select` at the root level, not in expanded entries or other query options. Only numeric operands and operators `add`, `sub`, `-`, `mul` and `div` are supported
+- `ias-auth`: configurable name for XSUAA fallback's `cds.requires` entry
+- `enterprise-messaging`: Support for scenario `ias-auth` with XSUAA fallback
+- Service configuration through `VCAP_SERVICES` can now be supplied with `VCAP_SERVICES_FILE_PATH`. Note that this is an experimental CF feature.
+
+### Changed
+
+- Internal service `UCLService` moved into non-extensible namespace `cds.core`
+- Status Transition Flows (`@flow`; beta):
+  + UI annotation generation is on by default. Switch off via `cds.features.annotate_for_flows=false`.
+  + Feature flag `cds.features.compile_for_flows` renamed to `cds.features.annotate_for_flows`
+- `DELETE` requests during draft edit, that do not use containment will cause persisted draft messages to be cleared
+
+### Fixed
+
+- Correctly format values in a where clause send to an external OData service, when the expression order is: value, operator, reference
+- cds.ql: tolerate extra spaces after in; parse RHS arrays of values as list
+- CRUD-style API: `cds.read()` et al. used without `await` do not throw if there is no database connected
+- Unnecessary compilation of model for edmx generation in multitenancy cases
+- Using `req.notify`, `req.warn` and `req.info` in custom draft handlers by collecting validation errors in a dedicated collection
+- `cds.auth` factory: passed options take precedence
+- `cds deploy --dry` no longer produces broken SQL for DB functions like `days_between`.
+- Read-after-write for create events during draft choreography will no longer include messages targeting siblings
+- `before` and `after` handlers now really run in parallel. If that causes trouble, you can restore the previous behavior with `cds.features.async_handler_compat=true` until `@sap/cds@10`.
+- Escaping of JSON escape sequences during localization
+
+## Version 9.4.5 - 2025-11-07
+
+### Fixed
+
+- Custom error message for `@assert.range`
+- For hierarchy requests with `$filter`, properly remove inner `where` clause
+- Calling a parameterless function with parameter
+- Aligned error handling for path navigation and `$expand`
+- Input validation immediately rejects for `@mandatory`
+
 ## Version 9.4.4 - 2025-10-23
 
 ### Fixed
@@ -109,7 +182,7 @@
   + For `@sap/xssec`-based authentication strategies, `cds.context.user.authInfo` is an instance of `@sap/xssec`'s `SecurityContext`
 - Support for status transition flows (`@flow`; alpha):
   + Generic handlers for validating entry (`@from`) and exit (`@to`) states
-  + Automatic addition of necessary annotations for Fiori UIs (`@Common.SideEffects` and `@Core.OperationAvailable`) during compile to EDMX with feature flag `cds.features.compile_for_flows=true`
+  + Automatic addition of necessary annotations for Fiori UIs (`@Common.SideEffects` and `@Core.OperationAvailable`) during compile to EDMX with feature flag `cds.features.compile_for_flows = true`
 - Experimental support for consuming remote HCQL services (`cds.requires.<remote>.kind = 'hcql'`)
 - Infrastructure for implementing the tenant mapping notification of Unified Customer Landscape's (UCL) Service Provider Integration Interface (SPII) API
   + Bootstrap the `UCLService` via `cds.requires.ucl = true` and implement the assign and unassign operations like so:
@@ -350,6 +423,13 @@
 - Deprecated stripping of unnecessary topic prefix `topic:` in messaging
 - Deprecated messaging `Outbox` class. Please use config or `cds.outboxed(srv)` to outbox your service.
 
+## Version 8.9.7 - 2025-11-07
+
+### Fixed
+
+- Reject navigations in `$expand` without parsing the navigation path
+- Aligned error handling for path navigation and `$expand`
+
 ## Version 8.9.6 - 2025-07-29
 
 ### Fixed

package/_i18n/messages_en_US_saptrc.properties

@@ -191,4 +191,4 @@ SINGLETON_NOT_NULLABLE=The singleton entity is not nullable
 #XMSG: Action "acceptTravel" requires "travelStatus" to be "Open".
 INVALID_FLOW_TRANSITION_SINGLE=35OYYAR7qBeFqZojBKMD7w_Action "{0}" requires "{1}" to be "{2}".
 #XMSG: Action "cancelTravel" requires "travelStatus" to be one of the following values: Open,Accepted.
-INVALID_FLOW_TRANSITION_MULTI=mqoLKfqWIZ4EX7lQDYHTzw_Action "{0}" requires "{1}" to be one of the following values: {2}.
+INVALID_FLOW_TRANSITION_MULTI=mqoLKfqWIZ4EX7lQDYHTzw_Action "{0}" requires "{1}" to be one of the following values: {2}.

package/common.cds

@@ -97,13 +97,16 @@ context sap.common {
     key locale: Locale;
   }
 
-  aspect FlowHistory {
+  aspect FlowHistory @(
+    cds.persistence.skip : 'if-unused'
+  ) {
+    @odata.draft.enabled : false
     transitions_ : Composition of many {
       key timestamp : managed:createdAt;
           user      : managed:createdBy;
           status    : String;
           comment   : String;
-    }
+    };
   }
 }
 

package/lib/compile/cds-compile.js

@@ -8,6 +8,7 @@ const compile = module.exports = Object.assign (cds_compile, {
     get nodejs() { return super.nodejs = require('./for/nodejs') }
     get lean_drafts() { return super.lean_drafts = require('./for/lean_drafts') }
     get flows() { return super.flows = require('./for/flows') }
+    get assert() { return super.assert = require('./for/assert') }
     get odata() { return super.odata = require('./for/odata') }
     get sql() { return super.sql = require('./for/sql') }
   },

package/lib/compile/for/assert.js

@@ -0,0 +1,64 @@
+const $collected = Symbol.for('collected')
+
+module.exports = function cds_compile_for_assert(csn) {
+  function _asserts4element(element, name, base) {
+    let xpr = element?.['@assert']?.xpr
+    if (!xpr) return
+
+    const inherited = base.elements[name]?.['@assert']?.xpr
+    if (inherited) {
+      // dedupe by splitting into "when ... then ..." blocks and filtering out own blocks already in @assert of projection target
+      const _inherited = _extract_cases(inherited).map(c => JSON.stringify(c))
+      const own = _extract_cases(xpr).filter(c => !_inherited.includes(JSON.stringify(c)))
+      if (own.length)
+        xpr = ['case', ...inherited.slice(1, -1), ...own.reduce((acc, cur) => (acc.push(...cur), acc), []), 'end']
+    }
+
+    return xpr
+  }
+
+  function _asserts4entity(entity) {
+    if (entity[$collected]) return
+
+    // buttom up collection of asserts -> process base entity first
+    projection: if (entity.projection || entity.query) {
+      // during compile for java, model is never linked -> no prototype chain
+      let base = (entity.projection || entity.query.SELECT)?.from?.ref?.[0]
+      if (!base) throw new Error(`Unable to determine base entity of ${entity.name}`)
+
+      base = csn.definitions[base]
+
+      // REVISIT: when compiling extensions, base may not be in the model -> OK to abort?
+      if (!base) break projection
+
+      _asserts4entity(base)
+
+      for (const each in entity.elements) {
+        const element = entity.elements[each]
+        if (element['@assert']) {
+          element['@assert']._xpr = element['@assert'].xpr
+          element['@assert'].xpr = _asserts4element(element, each, base)
+        }
+      }
+    }
+
+    entity[$collected] = true
+  }
+
+  for (const each in csn.definitions) {
+    const entity = csn.definitions[each]
+    if (entity.kind !== 'entity') continue
+    if (!entity.projection && !entity.query) continue
+
+    _asserts4entity(entity)
+  }
+}
+
+function _extract_cases(xpr) {
+  const cases = []
+  for (const each of xpr.slice(1, -1)) {
+    if (each === 'when') cases.push([])
+    cases.at(-1).push(each)
+  }
+  return cases
+}

package/lib/compile/for/flows.js

@@ -1,17 +1,14 @@
-// REVISIT: to be moved to cds-compiler later
-
 const cds = require('../../..')
 
+const { WELL_KNOWN_EVENTS } = require('../../req/event')
+
 const FLOW_STATUS = '@flow.status'
 const FROM = '@from'
 const TO = '@to'
-// backwards compat
-const FLOW_FROM = '@flow.from'
-const FLOW_TO = '@flow.to'
 const FLOW_PREVIOUS = '$flow.previous'
 
 const getFrom = action => {
-  let from = action[FROM] ?? action[FLOW_FROM]
+  let from = action[FROM]
   return Array.isArray(from) ? from : [from]
 }
 
@@ -19,7 +16,7 @@ function addOperationAvailableToActions(actions, statusEnum, statusElementName)
   for (const action of Object.values(actions)) {
     const fromList = getFrom(action)
     const conditions = fromList.map(from => {
-      const value = from['#'] ? (statusEnum[from['#']]?.val ?? from['#']) : from
+      const value = from['#'] ? statusEnum[from['#']]?.val ?? from['#'] : from
       return `$self.${statusElementName} = ${typeof value === 'string' ? `'${value}'` : value}`
     })
     const condition = `(${conditions.join(' OR ')})`
@@ -51,6 +48,44 @@ function addSideEffectToActions(actions, statusElementName) {
   }
 }
 
+function addActionsToTarget(targetAnnotation, entity, actions) {
+  const identification = (entity[targetAnnotation] ??= [])
+
+  for (const item of identification) {
+    if (
+      item.$Type === 'UI.DataFieldForAction' &&
+      !Object.hasOwn(item, '@UI.Hidden') &&
+      entity['@odata.draft.enabled'] === true
+    ) {
+      item['@UI.Hidden'] = {
+        '=': true,
+        xpr: [{ ref: ['$self', 'IsActiveEntity'] }, '=', { val: false }]
+      }
+    }
+  }
+
+  const existingActionNames =
+    identification?.filter(item => item.$Type === 'UI.DataFieldForAction').map(item => item.Action.split('.').pop()) ??
+    []
+
+  actions.forEach(action => {
+    const actionName = action.name
+    if (!existingActionNames.includes(actionName)) {
+      identification.push({
+        $Type: 'UI.DataFieldForAction',
+        Action: `${entity._service.name}.${actionName}`,
+        Label: action["@Common.Label"] ?? action["@title"] ?? `{i18n>${actionName}}`,
+        ...(entity['@odata.draft.enabled'] && {
+          '@UI.Hidden': {
+            '=': true,
+            xpr: [{ ref: ['$self', 'IsActiveEntity'] }, '=', { val: false }]
+          }
+        })
+      })
+    }
+  })
+}
+
 function resolveStatusEnum(csn, codeElem) {
   if (codeElem.enum !== undefined) return codeElem.enum
   if (codeElem.type) {
@@ -71,10 +106,12 @@ function enhanceCSNwithFlowAnnotations4FE(csn) {
       const fromActions = []
       const toActions = []
       for (const action of Object.values(entity.actions)) {
-        if (action[FROM] || action[FLOW_FROM]) fromActions.push(action)
-        if (action[TO] || action[FLOW_TO]) toActions.push(action)
+        if (action[FROM]) fromActions.push(action)
+        if (action[TO]) toActions.push(action)
       }
       if (fromActions.length === 0 && toActions.length === 0) continue
+      addActionsToTarget('@UI.Identification', entity, toActions)
+      addActionsToTarget('@UI.LineItem', entity, toActions)
       if (element.enum) {
         // Element is an enum directly
         addSideEffectToActions(toActions, elemName)
@@ -86,8 +123,10 @@ function enhanceCSNwithFlowAnnotations4FE(csn) {
           const codeElem = targetDef.elements.code
           const statusEnum = resolveStatusEnum(csn, codeElem)
           if (statusEnum) {
-            addSideEffectToActions(toActions, elemName + '.code')
-            addOperationAvailableToActions(fromActions, statusEnum, elemName + '.code')
+            // REVISIT: is there no way to know from the CSN?
+            const statusElementName = csn._4java ? elemName + '.code' : elemName + '_code'
+            addSideEffectToActions(toActions, statusElementName)
+            addOperationAvailableToActions(fromActions, statusEnum, statusElementName)
           }
         }
       } else if (element['@odata.foreignKey4']) {
@@ -103,66 +142,163 @@ function enhanceCSNwithFlowAnnotations4FE(csn) {
 }
 
 module.exports = function cds_compile_for_flows(csn) {
-  let flowHistory
-
-  for (const name in csn.definitions) {
-    const def = csn.definitions[name]
+  const { history_for_flows } = cds.env.features
 
-    if (!def.kind || def.kind !== 'entity' || !def.actions || def.elements?.transitions_) continue
-
-    let history
-    if (cds.env.features.history_for_flows === 'all') {
-      for (const each in def.elements) {
-        if (def.elements[each]['@flow.status']) {
-          history = true
-          break
+  const _requires_history = !history_for_flows
+    ? () => false
+    : history_for_flows === 'all'
+    ? def => {
+        for (const each in def.elements) {
+          if (def.elements[each]['@flow.status']) {
+            return true
+          }
         }
       }
-    } else {
-      for (const each in def.actions) {
-        const action = def.actions[each]
-        if (action && (action[TO]?.['='] === FLOW_PREVIOUS || action[FLOW_TO]?.['='] === FLOW_PREVIOUS)) {
-          history = true
-          break
+    : def => {
+        for (const each in def.actions) {
+          const action = def.actions[each]
+          if (action && action[TO]?.['='] === FLOW_PREVIOUS) {
+            return true
+          }
         }
       }
+
+  /*
+   * 1. propagate flows for well-known actions from extensions to definitions
+   */
+  if (csn.extensions) {
+    for (const ext of csn.extensions) {
+      if (!ext.actions) continue
+      const def = csn.definitions[ext.annotate]
+      if (!def || !def.kind || def.kind !== 'entity') continue
+      for (const each in ext.actions) {
+        if (!(each in WELL_KNOWN_EVENTS)) continue
+        def.actions ??= {}
+        def.actions[each] ??= { kind: 'action' }
+        Object.assign(def.actions[each], ext.actions[each])
+      }
     }
-    if (!history) continue
+  }
 
-    flowHistory ??= csn.definitions['sap.common.FlowHistory']
-    if (!flowHistory) cds.error('Cannot find definition sap.common.FlowHistory')
+  const extensions = new Set()
+  const exclusions = new Set()
 
-    const { elements: aspectElements } = flowHistory.elements.transitions_.targetAspect
+  for (const name in csn.definitions) {
+    const def = csn.definitions[name]
 
-    def.includes ??= []
-    def.includes.push('sap.common.FlowHistory')
-    def.elements.transitions_ = JSON.parse(`{
+    /*
+     * 2. propagate @flow.status to respective element and make it @readonly
+     */
+    if (def['@flow.status']?.['=']) {
+      const element = def.elements?.[def['@flow.status']['=']]
+      if (element) {
+        element['@flow.status'] = true
+        if (!('@readonly' in element)) element['@readonly'] = true
+      }
+    }
+
+    if (!def.kind || def.kind !== 'entity' || !def.actions) continue
+
+    /*
+     * 3. normalize @from and @to annotations
+     */
+    for (const each in def.actions) {
+      const action = def.actions[each]
+      if (action['@flow.from']) action['@from'] = action['@flow.from']
+      if (action['@flow.to']) action['@to'] = action['@flow.to']
+    }
+
+    /*
+     * 4. automatically apply aspect FlowHistory if needed and not present yet
+     */
+    if (!_requires_history(def)) continue
+
+    const projections = _get_projection_stack(name, csn)
+    const base_name = projections.pop()
+    const base = csn.definitions[base_name]
+    if (base.elements?.transitions_) continue //> manually added -> don't interfere
+
+    // add aspect FlowHistory to db entity
+    extensions.add(base_name)
+
+    // hack for "excludes" not possible via extensions
+    if (projections.length) projections.forEach(p => exclusions.add(p))
+  }
+
+  if (extensions.size) {
+    // REVISIT: ensure sap.common.FlowHistory is there
+    csn.definitions['sap.common.FlowHistory'] ??= JSON.parse(FlowHistory)
+
+    const _extensions = [...extensions].map(extend => ({ extend, includes: ['sap.common.FlowHistory'] }))
+    csn = cds.extend(csn).with({ extensions: _extensions })
+
+    // REVISIT: annotate all generated X.transitions_ with @cds.autoexpose: false
+    for (const each of extensions) csn.definitions[`${each}.transitions_`]['@cds.autoexpose'] = false
+  }
+
+  if (exclusions.size) {
+    for (const proj of exclusions) {
+      delete csn.definitions[proj].elements.transitions_
+      delete csn.definitions[`${proj}.transitions_`]
+    }
+  }
+
+  // REVISIT: annotate all X.transitions_ with @odata.draft.enabled: false
+  for (const name in csn.definitions)
+    if (name.endsWith('.transitions_')) csn.definitions[name]['@odata.draft.enabled'] = false
+
+  return csn
+}
+
+function _get_projection_stack(name, csn, stack = []) {
+  stack.push(name)
+  const def = csn.definitions[name]
+  if (def.projection || def.query) {
+    const base = (def.projection || def.query.SELECT)?.from?.ref?.[0]
+    if (!base) throw new Error(`Unable to determine base entity of ${name}`)
+    return _get_projection_stack(base, csn, stack)
+  }
+  return stack
+}
+
+const FlowHistory = `{
+  "kind": "aspect",
+  "@cds.persistence.skip": "if-unused",
+  "elements": {
+    "transitions_": {
+      "@odata.draft.enabled": false,
       "type": "cds.Composition",
       "cardinality": { "max": "*" },
-      "targetAspect": { "elements": ${JSON.stringify(aspectElements)} },
-      "target": "${name}.transitions_",
-      "on": [{ "ref": ["transitions_", "up_"] }, "=", { "ref": ["$self"] }]
-    }`)
-
-    const def_keys = Object.keys(def.elements)
-      .filter(k => def.elements[k].key)
-      .map(k => ({ ref: [k] }))
-    csn.definitions[`${name}.transitions_`] = JSON.parse(`{
-      "kind": "entity",
-      "elements": {
-        "up_": {
-          "key": true,
-          "type": "cds.Association",
-          "cardinality": { "min": 1, "max": 1 },
-          "target": "${name}",
-          "keys": ${JSON.stringify(def_keys)},
-          "notNull": true
-        },
-        ${JSON.stringify(aspectElements).slice(1, -1)}
+      "targetAspect": {
+        "elements": {
+          "timestamp": {
+            "@cds.on.insert": { "=": "$now" },
+            "@UI.HiddenFilter": true,
+            "@UI.ExcludeFromNavigationContext": true,
+            "@Core.Immutable": true,
+            "@title": "{i18n>CreatedAt}",
+            "@readonly": true,
+            "key": true,
+            "type": "cds.Timestamp"
+          },
+          "user": {
+            "@cds.on.insert": { "=": "$user" },
+            "@UI.HiddenFilter": true,
+            "@UI.ExcludeFromNavigationContext": true,
+            "@Core.Immutable": true,
+            "@title": "{i18n>CreatedBy}",
+            "@readonly": true,
+            "@description": "{i18n>UserID.Description}",
+            "type": "cds.String",
+            "length": 255
+          },
+          "status": { "type": "cds.String" },
+          "comment": { "type": "cds.String" }
+        }
       }
-    }`)
+    }
   }
-}
+}`
 
 module.exports.enhanceCSNwithFlowAnnotations4FE = enhanceCSNwithFlowAnnotations4FE
 module.exports.getFrom = getFrom