@sap/cds 7.6.3 → 7.7.0

package/libx/_runtime/common/utils/streamProp.js

@@ -2,7 +2,8 @@ const cds = require('../../cds')
 const { ensureNoDraftsSuffix, ensureUnlocalized } = require('../../fiori/utils/handler')
 const { isDuplicate } = require('./rewriteAsterisks')
 
-const _addColumn = (name, type, columns) => {
+const _addColumn = (name, type, columns, url) => {
+  if (cds.env.features.odata_new_adapter) return
   if (typeof type === 'object') {
     let mType = type['='].replaceAll(/\./g, '_')
     const ref = {
@@ -14,13 +15,22 @@ const _addColumn = (name, type, columns) => {
     const val = { val: type, as: `${name}@odata.mediaContentType` }
     if (!columns.find(isDuplicate(val))) columns.push(val)
   }
+
+  if (url) {
+    const ref = {
+      ref: [name],
+      as: `${name}@odata.mediaReadLink`
+    }
+    if (!columns.find(isDuplicate(ref))) columns.push(ref)
+  }
 }
 
 const _addColumns = (target, columns) => {
+  if (cds.env.features.odata_new_adapter) return
   for (const k in target.elements) {
     const el = target.elements[k]
     if (el['@Core.MediaType']) {
-      _addColumn(el.name, el['@Core.MediaType'], columns)
+      _addColumn(el.name, el['@Core.MediaType'], columns, el['@Core.IsURL'])
     }
   }
 }
@@ -38,11 +48,11 @@ const handleStreamProperties = (target, columns, model) => {
 
     if (col === '*') {
       _addColumns(target, columns)
-    } else if (col.ref && type === 'cds.LargeBinary') {
+    } else if (col.ref && (type === 'cds.LargeBinary' || mediaType)) {
       if (mediaType) {
-        _addColumn(name, mediaType, columns)
-      }
-      if ((mediaType || !cds.env.features.stream_compat) && !element['@Core.IsURL']) {
+        _addColumn(name, mediaType, columns, element['@Core.IsURL'])
+        columns.splice(index, 1)
+      } else if (!cds.env.features.stream_compat) {
         columns.splice(index, 1)
       }
     } else if (col.expand && col.ref) {

package/libx/_runtime/common/utils/ucsn.js

@@ -100,6 +100,7 @@ const _cleanup = (row, definition, cleanupNull, cleanupStruct, errors, prefix =
   }
 }
 
+// REVISIT: when needed?
 function convertStructured(service, definition, data, { cleanupNull = false, cleanupStruct = false, errors } = {}) {
   if (!definition) return
   // REVISIT check `structs` mode only for now as uCSN is not yet available

package/libx/_runtime/db/utils/columns.js

@@ -3,6 +3,10 @@ const resolveStructured = require('../../common/utils/resolveStructured')
 
 const { DRAFT_COLUMNS_MAP } = require('../../common/constants/draft')
 
+const _isStreamProperty = element => {
+  return element.type === 'cds.LargeBinary' || element['@Core.IsURL']
+}
+
 /**
  * This method gets all columns for an entity.
  * It includes the generated foreign keys from managed associations, structured elements and complex and custom types.
@@ -11,7 +15,7 @@ const { DRAFT_COLUMNS_MAP } = require('../../common/constants/draft')
  * @param entity - the csn entity
  * @returns {Array} - array of columns
  */
-const getColumns = (entity, { _4db, onlyKeys } = { _4db: true, onlyKeys: false }) => {
+const getColumns = (entity, { _4db, onlyKeys, omitStream } = { _4db: true, onlyKeys: false, omitStream: false }) => {
   // REVISIT is this correct or just a problem that occurs because of new structure we do not deal with yet?
   if (!(entity && entity.elements)) return []
   const columnNames = []
@@ -23,6 +27,7 @@ const getColumns = (entity, { _4db, onlyKeys } = { _4db: true, onlyKeys: false }
     const element = elements[elementName]
     if (element['@cds.api.ignore']) continue
     if (onlyKeys && !element.key) continue
+    if (omitStream && _isStreamProperty(element)) continue
     if (element.isAssociation) continue
     if (!lean_draft && _4db && entity._isDraftEnabled && elementName in DRAFT_COLUMNS_MAP) continue
     if (structs && element.elements) {

package/libx/_runtime/fiori/generic/activate.js

@@ -171,9 +171,17 @@ const fioriGenericActivate = async function (req, next) {
     })
   ])
 
-  // REVISIT: we need to use okra API here because it must be set in the batched request
-  // status code must be set in handler to allow overriding for FE V2
-  if (event === 'CREATE') req?._?.odataRes?.setStatusCode(201, { overwrite: true })
+  if (event === 'CREATE') {
+    // REVISIT: we need to use okra API here because it must be set in the batched request
+    //          status code must be set in handler to allow overriding for FE V2
+    // REVISIT: needs reworking for new adapter, especially re $batch
+    if (req._?.odataRes) {
+      req._?.odataRes?.setStatusCode(201, { overwrite: true })
+    } else if (req.http?.res) {
+      req.http.res.status(201)
+    }
+  }
+
   return result
 }
 

package/libx/_runtime/fiori/generic/edit.js

@@ -141,8 +141,14 @@ const fioriGenericEdit = async function (req, next) {
   await Promise.all(insertCQNs.map(CQN => dbtx.run(CQN)))
 
   // REVISIT: we need to use okra API here because it must be set in the batched request
-  // status code must be set in handler to allow overriding for FE V2
-  req?._?.odataRes?.setStatusCode(201, { overwrite: true })
+  //          status code must be set in handler to allow overriding for FE V2
+  // REVISIT: needs reworking for new adapter, especially re $batch
+  if (req._?.odataRes) {
+    req._?.odataRes?.setStatusCode(201, { overwrite: true })
+  } else if (req.http?.res) {
+    req.http.res.status(201)
+  }
+
   return results[0][0]
 }
 

package/libx/_runtime/fiori/lean-draft.js

@@ -8,31 +8,71 @@ const original = Symbol('original')
 const DRAFT_PARAMS = Symbol('draftParams')
 const AGGREGATION_FUNCTIONS = ['sum', 'min', 'max', 'avg', 'count']
 
+const calcTimeMs = timeout => {
+  const match = timeout.match(/^([0-9]+)(w|d|h|hrs|min)$/)
+  if (!match) return
+  const [, val, t] = match
+  switch (t) {
+    case 'w':
+      return val * 1000 * 3600 * 24 * 7
+    case 'd':
+      return val * 1000 * 3600 * 24
+    case 'h':
+    case 'hrs':
+      return val * 1000 * 3600
+    case 'min':
+      return val * 1000 * 60
+    default:
+      return val
+  }
+}
+
+const _config_to_ms = (config, _default) => {
+  const timeout = cds.env.fiori?.[config]
+  let timeout_ms
+  if (timeout === true) {
+    timeout_ms = calcTimeMs(_default)
+  } else if (typeof timeout === 'string') {
+    timeout_ms = calcTimeMs(timeout)
+    if (!timeout_ms)
+      throw new Error(`
+${timeout} is an invalid value for \`cds.fiori.${config}\`.
+Please provide a value in format /^([0-9]+)(w|d|h|hrs|min)$/.
+`)
+  } else {
+    timeout_ms = timeout
+  }
+
+  return timeout_ms
+}
+
 const DEL_TIMEOUT = {
   get value() {
-    const delTimeout = cds.env.fiori?.draft_deletion_timeout
-    const timeout = delTimeout && delTimeout !== false && delTimeout === true ? '30d' : delTimeout
-    let parts
-    if (typeof timeout === 'string') {
-      parts = timeout.match(/^([0-9]+)(d|h)$/)
-      if (!parts && !Number(timeout)) throw new Error('Invalid value for `cds.fiori.draft_deletion_timeout`')
+    const timeout_ms = _config_to_ms('draft_deletion_timeout', '30d')
+    Object.defineProperty(DEL_TIMEOUT, 'value', { value: timeout_ms })
+    return timeout_ms
+  }
+}
+
+const LOCK_TIMEOUT = {
+  get value() {
+    let timeout_ms = _config_to_ms('draft_lock_timeout', '15min')
+
+    const deprecated = cds.env.drafts?.cancellationTimeout // in min
+    if (deprecated) {
+      // in order to still support legacy use cases for tests, e. g. 0.000001
+      timeout_ms = deprecated * 1000 * 60
     }
-    const result =
-      parts && parts.length
-        ? parts[2] === 'd'
-          ? Number(parts[1]) * 1000 * 3600 * 24
-          : Number(parts[1]) * 1000 * 3600
-        : Number(timeout) || 0
-
-    Object.defineProperty(DEL_TIMEOUT, 'value', { value: result })
-    return result
+
+    Object.defineProperty(LOCK_TIMEOUT, 'value', { value: timeout_ms })
+    return timeout_ms
   }
 }
 
 const reject_bypassed_draft = req => {
   const msg =
     !cds.profiles?.includes('production') &&
-    '`cds.env.fiori.bypass_draft` must be enabled to support the directly modification of active instances.'
+    '`cds.env.fiori.bypass_draft` must be enabled or the entity must be annotated with `@odata.draft.bypass` to support the directly modification of active instances.'
   return req.reject(501, msg)
 }
 
@@ -116,13 +156,10 @@ const _inProcessByUserXpr = lockShiftedNow => ({
 
 const _lock = {
   get shiftedNow() {
-    return new Date(Math.max(0, Date.now() - DRAFT_CANCEL_TIMEOUT_IN_MIN() * 60 * 1000)).toISOString()
+    return new Date(Math.max(0, Date.now() - LOCK_TIMEOUT.value)).toISOString()
   }
 }
 
-const DRAFT_CANCEL_TIMEOUT_IN_MIN = () =>
-  (cds.env.drafts?.cancellationTimeout && Number(cds.env.drafts?.cancellationTimeout)) || 15
-
 const _redirectRefToDrafts = (ref, model) => {
   const [root, ...tail] = ref
   const draft = model.definitions[root.id || root].drafts
@@ -281,7 +318,7 @@ cds.ApplicationService.prototype.handle = async function (req) {
   if (req.event === 'NEW' || req.event === 'CANCEL' || req.event === 'draftPrepare') {
     if (req.event === 'draftPrepare' && draftParams.IsActiveEntity) req.reject(400)
     if (req.event === 'NEW' && req.data?.IsActiveEntity === true) {
-      if (!cds.env.fiori.bypass_draft) return reject_bypassed_draft(req)
+      if (!cds.env.fiori.bypass_draft && !req.target['@odata.draft.bypass']) return reject_bypassed_draft(req)
       const containsDraftRoot =
         this.model.definitions[query.INSERT.into?.ref?.[0]?.id || query.INSERT.into?.ref?.[0] || query.INSERT.into][
           '@Common.DraftRoot.ActivationAction'
@@ -390,6 +427,19 @@ cds.ApplicationService.prototype.handle = async function (req) {
     const HasActiveEntity = res.HasActiveEntity
     delete res.HasActiveEntity
 
+    if (cds.env.features.cds_assert) {
+      const assertOptions = { path: [req.target.actions[req.event]['@cds.odata.bindingparameter.name'] || 'in'] }
+      const errs = cds.assert(res, req.target, assertOptions)
+      if (errs) {
+        if (errs.length === 1) throw Object.assign(errs[0], { '@Common.numericSeverity': 4 })
+        throw Object.assign(new Error('MULTIPLE_ERRORS'), {
+          statusCode: 400,
+          details: errs,
+          '@Common.numericSeverity': 4 //> TODO: should not be needed here
+        })
+      }
+    }
+
     // First run the handlers as they might need access to DraftAdministrativeData or the draft entities
     const result = await run(
       HasActiveEntity
@@ -402,12 +452,18 @@ cds.ApplicationService.prototype.handle = async function (req) {
       DELETE.from('DRAFT.DraftAdministrativeData').where({ DraftUUID: DraftAdministrativeData_DraftUUID })
     ])
 
-    if (!HasActiveEntity) req?._?.odataRes?.setStatusCode(201, { overwrite: true })
+    if (!HasActiveEntity) {
+      // REVISIT: we need to use okra API here because it must be set in the batched request
+      //          status code must be set in handler to allow overriding for FE V2
+      // REVISIT: needs reworking for new adapter, especially re $batch
+      if (req._?.odataRes) {
+        req._?.odataRes?.setStatusCode(201, { overwrite: true })
+      } else if (req.http?.res) {
+        req.http.res.status(201)
+      }
+    }
 
     return Object.assign(result, { IsActiveEntity: true })
-
-    // REVISIT: we need to use okra API here because it must be set in the batched request
-    // status code must be set in handler to allow overriding for FE V2
   }
 
   if (req.target.actions?.[req.event] && draftParams.IsActiveEntity === false) {
@@ -457,7 +513,7 @@ cds.ApplicationService.prototype.handle = async function (req) {
 
     LOG.debug('patch active')
 
-    if (!cds.env.fiori.bypass_draft) return reject_bypassed_draft(req)
+    if (!cds.env.fiori.bypass_draft && !req.target['@odata.draft.bypass']) return reject_bypassed_draft(req)
 
     const entityRef = query.UPDATE.entity.ref
 
@@ -549,6 +605,7 @@ const Read = {
   unchanged: async function (run, query) {
     LOG.debug('List Editing Status: Unchanged')
     const draftsQuery = query._drafts
+    if (!draftsQuery) throw new Error('Invalid draft request')
     draftsQuery.SELECT.count = undefined
     draftsQuery.SELECT.orderBy = undefined
     draftsQuery.SELECT.limit = null
@@ -564,6 +621,8 @@ const Read = {
   ownDrafts: async function (run, query) {
     LOG.debug('List Editing Status: Own Draft')
 
+    if (!query._drafts) throw new Error('Invalid draft request')
+
     // read active from draft
     if (!query._drafts._target?.name.endsWith('.drafts')) {
       const result = await run(query._drafts)
@@ -758,6 +817,8 @@ const Read = {
 
   activesFromDrafts: async function (run, query, { isLocked = true }) {
     const draftsQuery = query._drafts
+    if (!draftsQuery) throw new Error('Invalid draft request')
+
     const additionalCols = draftsQuery.SELECT.columns
       ? draftsQuery.SELECT.columns.filter(
           c => c.ref && ['DraftAdministrativeData', 'DraftAdministrativeData_DraftUUID'].includes(c.ref[0])
@@ -1051,7 +1112,10 @@ function _cleansed(query, model) {
       }
       if (ignoredElements.has(e) && xpr[i + 2]) {
         let { val } = xpr[i + 2]
-        draftParams[x.ref.join('_')] = xpr[i + 1] === '!=' ? (typeof val === 'boolean' ? !val : 'not ' + val) : val
+        const param = x.ref.join('_')
+        // outer-most parameters win
+        if (draftParams[param] === undefined)
+          draftParams[param] = xpr[i + 1] === '!=' ? (typeof val === 'boolean' ? !val : 'not ' + val) : val
         i += 2
         const last = cleansed[cleansed.length - 1]
         if (last === 'and' || last === 'or') cleansed.pop()
@@ -1293,7 +1357,7 @@ async function onEdit(req) {
   }
 
   if (!res) req.reject(404)
-  const preserveChanges = req.context?.data?.PreserveChanges
+  const preserveChanges = req.data?.PreserveChanges
   const inProcessByUser = draft?.DraftAdministrativeData?.InProcessByUser
 
   if (draft) {
@@ -1327,8 +1391,13 @@ async function onEdit(req) {
   await INSERT.into(targetDraft).entries(res)
 
   // REVISIT: we need to use okra API here because it must be set in the batched request
-  // status code must be set in handler to allow overriding for FE V2
-  req?._?.odataRes?.setStatusCode(201, { overwrite: true })
+  //          status code must be set in handler to allow overriding for FE V2
+  // REVISIT: needs reworking for new adapter, especially re $batch
+  if (req._?.odataRes) {
+    req._?.odataRes?.setStatusCode(201, { overwrite: true })
+  } else if (req.http?.res) {
+    req.http.res.status(201)
+  }
 
   return { ...res, IsActiveEntity: false } // REVISIT: Flatten?
 }

package/libx/_runtime/hana/execute.js

@@ -15,6 +15,7 @@ const {
   readStreamWithHdb
 } = require('./streaming')
 const { convertStream } = require('../db/utils/stream')
+const { isBase64String } = require('../../common/assert/utils')
 
 function _cqnToSQL(model, query, user, locale, txTimestamp) {
   return sqlFactory(
@@ -48,8 +49,6 @@ function _getBinaries(stmt) {
   }, [])
 }
 
-const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}={2})$/
-
 function _getProcedureNameAndSchema(sql) {
   // name delimited with "" allows any character
   const match = sql
@@ -142,9 +141,7 @@ function _executeAsPreparedStatement(dbc, sql, values, reject, resolve) {
         const vals = Array.isArray(values[0]) ? values : [values]
         for (const i of binaries) {
           for (const row of vals) {
-            if (row[i] && typeof row[i] === 'string' && row[i].match(BASE64)) {
-              row[i] = Buffer.from(row[i], 'base64')
-            }
+            if (row[i] && isBase64String(row[i])) row[i] = Buffer.from(row[i], 'base64')
           }
         }
       }

package/libx/_runtime/messaging/service.js

@@ -126,8 +126,12 @@ class MessagingService extends cds.Service {
       const subscribedEvent =
         this.subscribedTopics.get(_msg.event) ||
         (this.wildcarded && this.subscribedTopics.get(this.wildcarded(_msg.event)))
-      if (!subscribedEvent && !this._listenToAll.value)
-        throw new Error(`No handler for incoming message with topic '${_msg.event}' found.`)
+      if (!subscribedEvent && !this._listenToAll.value) {
+        const err = new Error(`No handler for incoming message with topic '${_msg.event}' found.`)
+        err.code = 'NO_HANDLER_FOUND' // consumers might want to react to that
+        throw err
+      }
+
       _msg.event = subscribedEvent || _msg.event
     }
     return _msg

package/libx/common/assert/index.js

@@ -0,0 +1,232 @@
+const { cds } = global
+
+const typeCheckers = require('./type')
+const { checkMandatory, checkEnum, checkRange, checkFormat } = require('./validation')
+const { getNested, getTarget, resolveCDSType, resolveSegment } = require('./utils')
+
+const NUMBER_TYPES = new Set(['cds.UInt8', 'cds.Int16', 'cds.Int32', 'cds.Integer', 'cds.Double'])
+
+const _no_op = () => {}
+
+const _reject_unknown = (_, k, def, errs) =>
+  errs.push(new cds.error(`Property ${k} does not exist in ${def.name}`, { statusCode: 400, code: '400' }))
+
+const _filter_unknown = (obj, k) => delete obj[k]
+
+const _handle_mandatories = (obj, def, errs, path) => {
+  for (const [k, ele] of def._mandatories) {
+    const v = obj[k] === undefined ? getNested(k, obj) : obj[k]
+    checkMandatory(v, ele, errs, path, k)
+  }
+}
+
+const _handle_mandatories_if_insert = (obj, def, errs, path) => {
+  if (!def.keys) return _handle_mandatories(obj, def, errs, path)
+  const allKeysProvided = Object.keys(def.keys).every(k => k in obj)
+  for (const [k, ele] of def._mandatories) {
+    const v = obj[k] === undefined ? getNested(k, obj) : obj[k]
+    if (!allKeysProvided || v !== undefined) checkMandatory(v, ele, errs, path, k)
+  }
+}
+
+function _recurse(obj, prefix, def, errs, opts) {
+  for (const [k, v] of Object.entries(obj)) {
+    if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+      _recurse(v, prefix + k + '_', def, errs, opts)
+      continue
+    }
+    const flat = { [prefix + k]: v }
+    _process(flat, def, errs, opts)
+    if (!Object.keys(flat).length) delete obj[k] //> filtered out inside _process -> propagate to original object
+  }
+}
+
+function _process(obj, def, errs, opts) {
+  if (obj == null) return
+
+  if (Array.isArray(obj)) {
+    for (const row of obj) _process(row, def, errs, opts)
+    return
+  }
+
+  // TODO: path should be cqn
+  const prev = opts.path.length && opts.path[opts.path.length - 1]
+  if (prev?.keys || prev?.index) opts.path[opts.path.length - 1] = resolveSegment(prev, obj, def)
+
+  if (def._mandatories?.length) opts._handle_mandatories(obj, def, errs, opts.path)
+
+  for (let [k, v] of Object.entries(obj)) {
+    let ele = def.elements?.[k] || def.params?.[k] || def.items
+
+    /*
+     * TODO: should we support this? with or without transformation?
+     * structured vs flat
+     *   the combination of the two cases below SHOULD cover mixed cases like
+     *   foo: { bar: { baz: { ... } } } and foo_bar: { baz: { ... } }
+     *   TODO: add tests!!!
+     */
+    // case 1: structured data but flat model
+    if (
+      !ele &&
+      typeof obj[k] === 'object' &&
+      !Array.isArray(obj[k]) &&
+      (def.elements || def.params) &&
+      Object.keys(def.elements || def.params).find(key => key.startsWith(`${k}_`))
+    ) {
+      _recurse(obj[k], k + '_', def, errs, opts)
+      continue
+    }
+    // case 2: flat data but structured model
+    if (!ele && k.split('_').length > 1) {
+      // TODO: handle stuff like foo__bar, i.e., foo_: { bar: ... }
+      const parts = k.split('_')
+      let cur = def.elements || def.params
+      while (cur && parts.length) cur = (cur.elements || cur.params)?.[parts.shift()]
+      if (cur) ele = cur
+    }
+
+    if (!ele) {
+      if (!def['@open']) opts._handle_unknown(obj, k, def, errs)
+      continue
+    }
+
+    if (ele.isAssociation) {
+      const keys = ele.keys?.map(k => k.ref[0]) || Object.keys(ele._target.keys)
+      opts.path.push(ele.is2many || Object.keys(keys).length ? { assoc: k, keys } : k)
+      // NOTE: the assumption is that children with all keys provided are not inserted, but updated
+      // -> incomplete but best we can do without roundtrip
+      _process(v, ele._target, errs, {
+        ...opts,
+        _handle_mandatories:
+          opts.mandatories === false || ele._isAssociationStrict
+            ? _no_op
+            : opts.mandatories === true
+              ? _handle_mandatories
+              : _handle_mandatories_if_insert
+      })
+      opts.path.pop()
+      continue
+    }
+    if (ele._isStructured) {
+      opts.path.push(k)
+      _process(v, ele, errs, opts)
+      opts.path.pop()
+      continue
+    }
+    if (ele instanceof cds.builtin.classes.array) {
+      for (let i = 0; i < v.length; i++) {
+        opts.path.push({ prop: k, index: i })
+        const _def = ele.items?.__proto__.elements ? ele.items.__proto__ : ele.__proto__
+        const _obj = _def.elements ? v[i] : { [k]: v[i] }
+        _process(_obj, _def, errs, opts)
+        opts.path.pop()
+      }
+      continue
+    }
+
+    if (ele.notNull && v === null) {
+      const target = getTarget(opts.path, k)
+      errs.push(new cds.error('ASSERT_NOT_NULL', { target, statusCode: 400, code: '400' }))
+      continue
+    }
+
+    const type = resolveCDSType(ele)
+    if (type?.match(/^cds\.hana\./)) continue
+
+    let typeChecker = typeCheckers[type]
+    if (typeChecker) {
+      if (v == null) continue
+
+      // if used in protocol adapter, adjust val/ checker if necessary
+      if (opts.http) {
+        if (typeof v !== 'boolean') {
+          if (NUMBER_TYPES.has(type)) v = Number(v)
+          else if (type === 'cds.Double') v = parseFloat(v)
+
+          // REVISIT: consider ieee754 and exp dec headers?
+          // const ieee = opts.http.req?.headers['content-type'].match(/IEEE754Compatible=(\w+)/i)
+          // const exp = opts.http.req?.headers['content-type'].match(/ExponentialDecimals=(\w+)/i)
+          // if (type === 'cds.Decimal') {
+          //   TODO
+          // }
+        }
+      }
+
+      // use relaxed uuid check if not in strict mode
+      if (type === 'cds.UUID' && !opts.strict) typeChecker = typeCheckers['relaxed.UUID']
+
+      // type check
+      // REVISIT: all checkers should add errors themselves!
+      if (type === 'cds.Decimal')
+        typeChecker(v, ele, errs, opts.path, k) //> _checkDecimal adds error itself
+      else if (!typeChecker(v, ele) || (opts.strict && typeChecker.name === '_checkBuffer' && typeof v === 'string')) {
+        errs.push(
+          new cds.error('ASSERT_DATA_TYPE', {
+            args: [typeof obj[k] === 'string' ? `"${obj[k]}"` : obj[k], ele._type],
+            target: getTarget(opts.path, k),
+            statusCode: 400,
+            code: '400'
+          })
+        )
+      }
+
+      // propagate correction if necessary
+      if (obj[k] !== v) obj[k] = v
+
+      // @assert
+      if (ele['@assert.enum'] || (ele['@assert.range'] && ele.enum)) checkEnum(v, ele, errs, opts.path, k)
+      if (ele['@assert.range']) checkRange(v, ele, errs, opts.path, k)
+      if (ele['@assert.format']) checkFormat(v, ele, errs, opts.path, k)
+      // REVISIT: @assert.target? -> no because async, but maybe return the necessary query to execute?
+
+      continue
+    }
+
+    throw new Error(`Missing type check for "${ele.type}" (property "${k}" of "${def.name}")`)
+  }
+}
+
+/**
+ * Asserts the given data against the given CSN definition and returns an array of errors or undefined.
+ *
+ * @param {object} data - the data to be checked
+ * @param {LinkedCSN} definition - the CSN definition to which the data should be checked against
+ * @param {object} [options] - options
+ * @param {boolean} [options.strict] - if true, an error is thrown if a property is not defined in the CSN
+ * @param {boolean} [options.filter] - if true, properties not defined in the CSN are filtered out
+ * @param {boolean} [options.mandatories] - if false, mandatory properties are never checked.
+ *   if true, mandatory properties are always checked.
+ *   if undefined, mandatory properties are checked for presumed insert rows only (determined by a heuristic to avoid roundtrip).
+ * @param {object} [options.http] - the HTTP request object providing access to headers, etc.
+ * @param {*[]} [options.path] - collector for the current path, should not be set manually
+ * @return {Array} - an array of errors or undefined if no errors
+ */
+module.exports = (data, definition, options = {}) => {
+  if (!data) throw new Error('Argument "data" was not provided')
+  if (typeof data !== 'object') throw new Error('Argument "data" must be an object (or an array)')
+
+  if (!definition) throw new Error('Argument "entity" was not provided')
+  // FIXME: definition instanceof cds.builtin.classes.any doesn't always work for some reason
+  if (!(definition instanceof cds.builtin.classes.any) && !(definition.kind in { entity: 1, action: 1, function: 1 })) {
+    throw new Error('Argument "definition" is not a valid CSN element')
+  }
+
+  // TODO: feature flags instead of process env vars
+  options.strict ??= process.env.CDS_ASSERT_STRICT === 'true'
+  options.filter ??= process.env.CDS_ASSERT_FILTER === 'true'
+  options.path ??= []
+
+  // materialize what is done ...
+  // ... in case of unknown elements
+  if (options.strict) options._handle_unknown = _reject_unknown
+  else if (options.filter) options._handle_unknown = _filter_unknown
+  else options._handle_unknown = _no_op
+  // ... regarding mandatory elements
+  if (options.mandatories === false) options._handle_mandatories = _no_op
+  else if (options.mandatories === true) options._handle_mandatories = _handle_mandatories
+  else options._handle_mandatories = _handle_mandatories_if_insert
+
+  const errs = []
+  _process(data, definition, errs, options)
+  return errs.length ? errs : undefined
+}