@sap/cds-dk 9.9.3 → 10.0.3

package/node_modules/@sap/cds/lib/req/validate.js

@@ -0,0 +1,339 @@
+const cds = require('..')
+
+const { WELL_KNOWN_EVENTS } = require('./event')
+
+/** Validates given input data against a request target definition.
+ * @param {entity} target the linked definition to check against, usually an entity definition
+ * @returns {Error[]|undefined} an array of errors or undefined if no errors occurred
+ */
+const conf = module.exports = exports = function validate (data, target, options={}) {
+  const vc = new Validation (data, target, options)
+  target.validate (data, null, vc)
+  return vc.errors
+}
+
+const ValidationError = Object.create (Error.prototype, {
+  name: { value: 'ValidationError' },
+  stack: { configurable:true, get() { return this.message } },
+  message: { writable:true, configurable:true },
+  status: { value: 400 },
+})
+
+/** Instances represent single validations and are mainly used to record errors during validation. */
+class Validation {
+
+  constructor (data, target, options={}) {
+    this.data = data
+    this.target = target
+    this.protocol = options.protocol
+    this.options = options
+    this.insert = options.insert ?? options.mandatories
+    this.rejectIgnore = options.rejectIgnore
+    this.cleanse = options.cleanse !== false
+  }
+
+  error (code, path, leaf, message, args) {
+    const err = Object.create (ValidationError); (this.errors ??= []).push(err)
+    err.code = code
+    if (typeof message === 'string') err.message = message
+    if (args) err.args = args
+    if (path) {
+      if (leaf) path = [ ...path, leaf ]
+      if (this.options.path) path = [ this.options.path, ...path ] // e.g. used to prefix 'in/' for actions
+      err.target = path.reduce((p,n) => this._targetFromPath(p,n),'')
+      // err.path = path.map (p => p?.index || p)
+    }
+    return err
+  }
+
+  _targetFromPath (p,n) {
+    if (n === undefined) return p
+    if (n.row) return p + this.filter4(n)          // > some/entity(ID=1)...
+    if (typeof n === 'number') return p + `[${n}]` // > some/array[1]...
+    if (p && n) return p+'/'+n                     // > some/element...
+    return n    
+  }
+
+  filter4 ({ def, row, index }) {
+    if (this.target.kind in { 'action': 1, 'function': 1 }) return '' //> no filter for operations
+    const entity = def._target || def, filter=[]
+    for (let k in entity.keys) {
+      let v = row[k]
+      if (v === undefined) if (k === 'IsActiveEntity') v = false; else continue
+      else if (typeof v === 'string' && !entity.elements[k].isUUID || entity.elements[k]['@odata.Type'] === 'Edm.String') v = `'${v}'`
+      filter.push (`${k}=${v}`)
+    }
+    if (filter.length) return `(${filter})`
+    if (index !== undefined) return `[${index}]`
+    return ''
+  }
+
+  unknown (e,d,input, path) {
+    if (this.protocol === 'odata' && e.match(/^\w*@\w+\.\w+$/)) return delete input[e] //> skip all annotations, like @odata.Type (according to OData spec annotations contain an "@" and a ".")
+    if (d['@open']) return
+    const target = d.name ?? path.reduce((p, n) => this._targetFromPath(p, n), '')
+    cds.error (400, `Property "${e}" does not exist in ${target}`, {target}) 
+  }
+}
+
+
+/** Adding basic validation capabilities to linked definitions. */
+const $any = class any {
+
+  /**
+   * Central method for validating input data against CSN definitions.
+   * @param {any} value the input value to validate
+   * @param {Array} path the path prefix to use for error messages
+   * @param {Validation} ctx the request object used to record errors
+   */
+  validate (value, path, ctx) {
+    this.check_asserts (value, path, ctx)
+  }
+
+  /**
+   * Checks the type of provided input values as well as @asserts specified.
+   * On first call, it constructs an optimized instance-specific override of
+   * this method for subsequent usages, with statically determined checks.
+   */
+  check_asserts (val, path, /** @type {Validation} */ ctx) {
+    // IMPORTANT: We need to use this.own() here as elements derived from reuse
+    // definitions or from elements of base entities might have different asserts
+    // than inherited ones.
+    const check_asserts = this.own('_check_asserts', () => {
+      const asserts = []
+      const type_check = conf.strict && this.strict_check || this.type_check
+      if (type_check) {
+        asserts.push ((v,p, /** @type {Validation} */ ctx) => v == null || type_check(v) || ctx.error ('ASSERT_DATA_TYPE', p, this.name, null, [ v, this.toString() ]))
+      }
+      if (this._is_mandatory()) {
+        asserts.push ((v,p, /** @type {Validation} */ ctx) => v != null && v.trim?.() !== '' || ctx.error ('ASSERT_MANDATORY', p, this.name, this['@mandatory.message'] || this['@mandatory'], [v]))
+      }
+      if (this['@assert.format']) {
+        const format = new RegExp(this['@assert.format'],'u')
+        asserts.push ((v,p, /** @type {Validation} */ ctx) => v == null || format.test(v) || ctx.error ('ASSERT_FORMAT', p, this.name, this['@assert.format.message'], [ v, this['@assert.format'] ]))
+      }
+      if (this['@assert.range'] && !this.enum) {
+        const [ min, max ] = this['@assert.range']
+        if (min['='] === '_') min.val = -Infinity
+        if (max['='] === '_') max.val = +Infinity
+        asserts.push (
+          min.val !== undefined && max.val !== undefined ? (v,p, /** @type {Validation} */ ctx) => v == null || min.val < v && v < max.val || ctx.error ('ASSERT_RANGE', p, this.name, this['@assert.range.message'], [ v, '>'+min.val, '<'+max.val ]) :
+          min.val !== undefined ? (v,p, /** @type {Validation} */ ctx) => v == null || min.val < v && v <= max || ctx.error ('ASSERT_RANGE', p, this.name, this['@assert.range.message'], [ v, '>'+min.val, max ]) :
+          max.val !== undefined ? (v,p, /** @type {Validation} */ ctx) => v == null || min <= v && v < max.val || ctx.error ('ASSERT_RANGE', p, this.name, this['@assert.range.message'], [ v, min, '<'+max.val ]) :
+          (v,p, /** @type {Validation} */ ctx) => v == null || min <= v && v <= max || ctx.error ('ASSERT_RANGE', p, this.name, this['@assert.range.message'], [ v, min, max ])
+        )
+      }
+      if (this['@assert.enum'] || this['@assert.range'] && this.enum) {
+        const vals = Object.entries(this.enum).map(([k,v]) => 'val' in v ? v.val : k)
+        const enums = vals.reduce((a,v) => (a[v]=true, a),{})
+        asserts.push ((v,p, /** @type {Validation} */ ctx) => v == null || v in enums || vals.some(x => x == v) || ctx.error ('ASSERT_ENUM', p, this.name, this['@assert.enum.message'], [ typeof v === 'string' ? `"${v}"` : v, vals.join(', ') ]))
+      }
+      if (!asserts.length) return ()=>{} // nothing to do
+      return (v,p,ctx) => asserts.forEach (a => a(v,p,ctx))
+    })
+    return check_asserts (val, path, ctx)
+  }
+
+  _is_mandatory (d=this) {
+    return d.own('_mandatory', ()=> {
+      if (d._is_readonly()) return false // readonly annotations have precedence over mandatory ones
+      if (d['@mandatory'] || d['@Common.FieldControl']?.['#'] === 'Mandatory') {
+        const q = d.parent?.query?.SELECT
+        if (!q) return true // it's a regular entity's element marked as mandatory
+        if (!q.from?.ref) return false // join or union -> elements can't be mandatory
+        const c = q.columns?.find (c => alias4(c) === d.name)
+        if (!c) return true // * or foo.* -> can't tell whether d is joined
+        if (!c.ref) return false // calculated fields aren't mandatory
+        if (c.ref.length === 1) return true // SELECT from Foo { foo }
+        if (c.ref.length === 2 && c.ref[0] === alias4(q.from)) return true // SELECT from Foo as f { f.foo }
+        else return false // joined field which can't be mandatory, e.g. SELECT from Books { author.name as author }
+        function alias4 (x) { return x.as || x.ref?.at(-1) }
+      }
+      if (d.notNull && !d.default && (d.parent?.kind === 'action' || d.parent?.kind === 'function')) return true // only for action/function params
+      else return false
+    })
+  }
+
+  _is_readonly (d=this) {
+    return d.own('_readonly', ()=> {
+      if (d['@readonly'])                                   return true
+      if (d['@cds.on.insert'])                              return true
+      if (d['@cds.on.update'])                              return true
+      if (d['@Core.Computed'])                              return true
+      if (d['@Common.FieldControl']?.['#'] === 'ReadOnly')  return true
+      else return false
+    })
+  }
+
+  _is_immutable (d=this) {
+    return d['@insertonly'] || d['@Core.Immutable']
+  }
+
+  /**
+   * Checks if a nested row of a deep update is in turn to be inserted or updated.
+   * This is the case if the row date does not contain all primary key elements of the target entity.
+   */
+  _is_insert (row) {
+    // IMPORTANT: We need to use this.own() here as derived entities might have
+    // different keys and thus different insert checks.
+    const _is_insert = this.own('__is_insert', () => {
+      const entity = this._target || this
+      let keys = Object.keys (entity.keys||{})
+      keys = keys.filter(k => !entity.elements[k].virtual)
+      if (!keys.length) return ()=> true
+      else return data => typeof data === 'object' && !keys.every(k => k in data)
+    })
+    return _is_insert(row)
+  }
+
+  _required (elements) {
+    // IMPORTANT: We need to use this.own() here as derived entities might have
+    // different elements or elements with different annotations than base entitites.
+    return this.own('__required', ()=> Object.values(elements).filter(this._is_mandatory))
+  }
+
+  /** Forward declaration for universal CSN */
+  get $struct() { return this['@odata.foreignKey4'] }
+}
+
+/** Structs iterate over their elements to validate them. */
+class struct extends $any {
+  validate (data, path, /** @type {Validation} */ ctx, elements = this.elements, skip={}) {
+    if (data == null) return
+    const path_ = !path ? [] : [...path, this.name]; if (path?.row) path_.push({...path})
+    if (typeof data !== 'object') return ctx.error ('ASSERT_DATA_TYPE', path_, null, null, [ data, this.target || this.type?.replace(/^cds\./,'') ])
+    // check for required elements in case of inserts -- note: null values are handled in the payload loop below
+    if (ctx.insert || data && path_.length && this._is_insert(data)) for (let each of this._required (elements)) {
+      if (each.name in data) continue // got value for required element
+      if (each.name in skip) continue // skip uplinks in deep inserts -> see Composition.validate()
+      if (each.$struct in data) continue // got struct for flattened element/fk, e.g. {author:{ID:1}}
+      if ((each.elements && each.kind !== 'param' ) || each.foreignKeys) continue // skip struct-likes as we check flat payloads above, and deep payloads via struct.validate(), parameters don't have flat elements
+      if (each.isAssociation) continue // unmanaged associations are always ignored (no value like)
+      else ctx.error ('ASSERT_MANDATORY', path_, each.name, each['@mandatory.message'] || each['@mandatory'])
+    }
+    // check values of given data
+    for (let each in data) { // will work for structured payloads as well as flattened ones with universal CSN
+      let /** @type {$any} */ d = Object.hasOwn(elements, each) && elements[each]
+      if (!d || (d['@cds.api.ignore'] && ctx.rejectIgnore)) ctx.unknown (each, this, data, path_)
+      else if (ctx.cleanse && d._is_readonly() && !d.key) delete data[each]
+      else if (ctx.cleanse && d._is_immutable() && !ctx.insert && !path) delete data[each] // @Core.Immutable processed only for root, children are handled when knowing db state
+      else if (d['@cds.validate'] !== false) d.validate (data[each], path_, ctx)
+    }
+  }
+}
+
+/** Array definitions validate the entries of an array against their items definition. */
+class array extends $any {
+  validate (data, path, /** @type {Validation} */ ctx) {
+    if (data == null) return super.validate (data, path, ctx)
+    if (!Array.isArray(data)) return ctx.error ('ASSERT_ARRAY', path, this.name)
+    const path_ = path?.concat(this.name)
+    const /** @type {$any} */ items = { __proto__:this.items, name: undefined }
+    data.forEach ((entry,i) => items.validate (entry, path_.concat(i), ctx))
+  }
+}
+
+/** Entities support both as input: single records as well as arrays of which. */
+class entity extends struct {
+  validate (data, path, ctx, ...more) {
+    const _path4 = !path ? ()=>path : (row,i) => ({__proto__:path, index:i, row, def:this})
+    if (!Array.isArray(data)) return super.validate (data, _path4(data), ctx, ...more)
+    return data.forEach ((row,i) => super.validate (row, _path4(row,i), ctx, ...more))
+  }
+}
+
+/** Actions are struct-like, with their parameters as elements to validate. */
+class action extends struct {
+  validate (data, path, ctx) {
+    if (this.name in WELL_KNOWN_EVENTS) return
+    super.validate (data, path, ctx, this.params || {})
+  }
+
+  _is_mandatory(e) { return e.notNull && !e.default || e._is_mandatory() } // params
+}
+
+/** Managed associations are struct-like, with foreign keys as elements to validate. */
+class Association extends struct {
+  validate (data, path, ctx) {
+    if (this.foreignKeys) super.validate (data, path, ctx, this.foreignKeys)
+  }
+}
+
+/** Compositions are like nested entities, validating deep input against their target entity definitions. */
+class Composition extends entity {
+  validate (data, path, ctx) { if (!data) return
+    if (this.is2many && !Array.isArray(data)) return ctx.error ('ASSERT_DATA_TYPE', path, this.name, null, [ data, 'array of ' + this._target.name ])
+    const _validate = this.own('_validate', () => {
+      const elements = this._target.elements
+      const uplinks = {} // statically determine the uplinks for this composition
+      if (this.on) for (let {ref} of this.on) if (ref?.[0] === this.name) {
+        const fk = ref[1], fk_ = fk+'_'; uplinks[fk] = true
+        for (let e in elements) if (e.startsWith(fk_)) uplinks[e] = true
+      }
+      return (data, path, ctx) => super.validate (data, path, ctx, elements, uplinks)
+    })
+    _validate (data, path, ctx)
+  }
+}
+
+
+// Type checks ---------------------------------------------------------------
+
+$any.prototype.type_check = undefined
+
+/**
+ * This getter constructs and returns a type check function for the declared precision and scale.
+ * Precision is the total number of digits, scale the number of digits after the decimal point.
+ */
+class Decimal extends $any { get type_check() {
+  const { precision:p, scale:s } = this, rx = RegExp (
+    !p ? `^[+-]?\\d+(?:\\.\\d+)?$` :
+    !s ? `^[+-]?\\d{1,${p}}$` :
+    p === s ? `^[+-]?0(?:\\.\\d{1,${s}})?$` :
+    /* p,s */ `^[+-]?\\d{1,${p-s}}(?:\\.\\d{1,${s}})?$`
+  )
+  return v => rx.test(v)
+}}
+
+class string extends $any { get type_check() {
+  const { length:l } = this; return l
+    ? v => typeof v === 'string' && v.length <= l
+    : v => typeof v === 'string'
+}}
+
+const {Readable} = require('stream')
+const _range_check = (range, min=-range) => v => min <= v && v < range
+const _regex_check = (rx) => v => rx.test(v)
+const _date_check  = (...parts) => {
+  const rx = RegExp('^'+parts.map(p => p.source||p).join('')+'$')
+  return v => v instanceof Date || rx.test(v)
+}
+const YYYY = /\d{4}/
+const MM = /-(0[1-9]|1[0-2])/
+const DD = /-(0[1-9]|[12]\d|3[01])/
+const hh = /[0-2]\d/
+const mm = /:[0-5]\d/
+const ss = /(?::[0-5]\d)?/
+const ms = /(?::[0-5]\d(?:\.\d+)?)?/
+const tz = /(?:Z|[+-][0-2]\d:?[0-5]\d)?/
+
+const $ = cds.linked.classes
+$.UUID.prototype        .strict_check = _regex_check (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+$.boolean.prototype     .strict_check = v => typeof v === 'boolean'
+$.boolean.prototype     .type_check = v => typeof v === 'boolean' || v === 0 || v === 1
+$.number.prototype      .type_check = v => !isNaN(v)
+$.Integer.prototype     .type_check = _range_check (2**53)
+$.Int16.prototype       .type_check = _range_check (2**15)
+$.Int32.prototype       .type_check = _range_check (2**31)
+$.Int64.prototype       .type_check = _range_check (2n**63n)
+$.UInt8.prototype       .type_check = _range_check (256+1,0)
+$.Time.prototype        .type_check = _date_check (hh,mm,ss)
+$.Date.prototype        .type_check = _date_check (YYYY,MM,DD)
+$.DateTime.prototype    .type_check = _date_check (YYYY,MM,DD,'(?:T',hh,mm,ss,tz,')?')
+$.Timestamp.prototype   .type_check = _date_check (YYYY,MM,DD,'(?:T',hh,mm,ms,tz,')?')
+$.Binary.prototype      .type_check = v => Buffer.isBuffer(v) || typeof v === 'string'
+$.LargeBinary.prototype .type_check = v => Buffer.isBuffer(v) || typeof v === 'string' || v instanceof Readable
+$.LargeString.prototype .type_check = v => Buffer.isBuffer(v) || typeof v === 'string' || v instanceof Readable
+
+// Mixin above class extensions to cds.linked.classes
+$.mixin ( Decimal, string, $any, action, array, struct, entity, Association, Composition )

package/node_modules/@sap/cds/lib/srv/bindings.js

@@ -0,0 +1,170 @@
+
+const cds = require ('..')
+const { exec } = require('child_process')
+const LOG = cds.log('serve|bindings',{label:'cds'})
+const registry = '~/.cds-services.json'
+const fs = require('fs')
+
+class Bindings {
+
+  provides = {}
+  servers = {}
+  #bound = {}
+
+  then (r,e) {
+    const info = ()=> LOG.info ('using bindings from:', { registry })
+    if (cds.watched) cds.prependOnceListener ('connect',info); else info()
+    delete Bindings.prototype.then // only once per process
+    cds.once('listening', server => this.export (cds.service.providers, server.url))
+    return this.import() .then (r,e)
+  }
+
+  bind (service) {
+    let required = cds.requires [service]
+    let binding = this.provides [service]
+
+    if (binding?.endpoints && !required?.credentials) {
+      // > Re-route requests to the mock service running locally
+
+      const server = this.servers [binding.server]
+      const kind = [ required?.kind, 'hcql', 'rest', 'odata' ].find (k => k in binding.endpoints)
+      const path = binding.endpoints [kind]
+
+      if (typeof required !== 'object') required = {}
+      cds.env.requires[service] = required = {
+        kind, ...cds.requires.kinds [kind], ...required,
+        credentials: {
+          ...required.credentials,
+          ...binding.credentials,
+          url: server.url + path
+        },
+      }
+      required.kind = kind // override kind from binding
+
+      // REVISIT: temporary fix to inherit kind as well for mocked odata services
+      // otherwise mocking with two services does not work for kind:odata-v2
+      if (kind === 'odata-v2' || kind === 'odata-v4') required.kind = 'odata'
+
+      // Finally, ensure the changes are mirrored in cds.requires overlays as well
+      if (required.service) cds.requires[required.service] = required
+    }
+
+    return this.#bound [service] = required
+  }
+
+  // used by cds.connect
+  at (service) {
+    return this.#bound [service] ??= this.bind (service)
+  }
+
+  get registry() {
+    return Bindings.registry ??= registry.replace(/^~/, require('os').homedir())
+  }
+
+  async load (read = fs.promises.readFile) {
+    LOG.debug ('reading bindings from:', registry)
+    try {
+      let src = read (this.registry)
+      let {cds} = JSON.parse (src.then ? await src : src)
+      Object.assign (this, cds)
+    }
+    catch { /* ignored */ }
+    return this
+  }
+
+  async store (write = fs.promises.writeFile) {
+    LOG.debug ('writing bindings to:', registry)
+    const json = JSON.stringify ({ cds: this },null,'  ')
+    return write (this.registry, json)
+  }
+
+  async import() {
+    await this.load()
+    for (let each in cds.env.requires) this.bind (each)
+    return this
+  }
+
+  async export (services, url) {
+    this.cleanup (url)
+    await this.cleanupStaleServers()
+
+    const { servers, provides } = this, { pid } = process
+    // register our server
+    servers[pid] = {
+      root: 'file://' + cds.root,
+      url
+    }
+    // register our services
+    for (let srv of services) {
+      // if (each.name in cds.env.requires)  continue
+      provides[srv.name] = {
+        endpoints: Object.fromEntries (srv.endpoints.map (ep => [ ep.kind, ep.path ])),
+        server: pid,
+      }
+    }
+    process.on ('exit', ()=> this.purge())
+    cds.on ('shutdown', ()=> this.purge())
+    return this.store()
+  }
+
+  purge() {
+    if (this.done) return;
+    this.load (fs.readFileSync)
+    LOG.debug ('purging bindings from:', registry)
+    this.cleanup()
+    this.store (fs.writeFileSync)
+    this.done = true
+  }
+
+  /**
+   * Remove all services served by this server or at the given url.
+   */
+  cleanup (url, pid=process.pid) {
+    const { servers, provides } = this
+    for (let [key,srv] of Object.entries (provides))
+      if (srv.server === pid || url && srv.credentials?.url?.startsWith(url)) delete provides [key]
+    delete servers [pid.toString()]
+    return this
+  }
+
+  async cleanupStaleServers() {
+    const { servers } = this
+    if (!Object.keys(servers).length) return
+
+    const pids = await new Promise((resolve) => {
+      const command = process.platform === 'win32' ? 'tasklist /fo csv /nh' : 'ps -e -o pid='
+      exec(command, (error, stdout) => {
+        if (error) {
+          LOG.warn('Error fetching process IDs with command:', command, error)
+          return resolve([])
+        }
+        resolve(stdout.split('\n').map(line => line.trim())
+          .map(line => {
+            if (process.platform === 'win32') {
+              const parts = line.split(',')
+              const pid = parts[1]?.replace(/"/g, '')
+              return pid ? parseInt(pid, 10) : NaN
+            }
+            return parseInt(line, 10)
+          })
+          .filter(pid => !isNaN(pid)))
+      })
+    })
+    LOG.debug(`fetched ${pids.length} PIDs`)
+    const pidSet = new Set(pids)
+    for (let key of Object.keys(servers)) {
+      const pid = parseInt(key, 10)
+      if (!pidSet.has(pid)) {
+        LOG.debug(`cleaning up bindings for stale PID ${pid}`)
+        this.cleanup(undefined, pid)
+      }
+    }
+  }
+}
+
+const {NODE_ENV} = process.env
+if (NODE_ENV === 'test' || global.it || cds.env.no_bindings) {
+  Object.defineProperty (module, 'exports', { value: { at: ()=> undefined }})
+} else {
+  module.exports = new Bindings
+}

package/node_modules/@sap/cds/lib/srv/cds-connect.js

@@ -0,0 +1,79 @@
+const cds = require('..'), LOG = cds.log('cds.connect')
+const TRACE = cds.debug('trace')
+
+/**
+ * Connect to a service as primary datasource, i.e. cds.db.
+ */
+const connect = module.exports = async function cds_connect (options) {
+  if (typeof options === 'object' && cds.db) throw cds.error (
+    `Re-connect to primary db with potentially different options is not allowed!`
+  )
+  if (typeof options === 'string') cds.db = await connect.to (options)
+  else await connect.to ('db',options)
+  return cds
+}
+
+/**
+ * Connect to a specific service, either served locally, with ad-hoc options
+ * or with options configured in cds.env.requires.<datasource>.
+ * @param { string|Function|object } [datasource]
+ * @param {{ kind?:String, impl?:String }} [options]
+ * @returns { Promise<import('./cds.Service')> }
+ */
+connect.to = (datasource, options) => {
+  let Service = cds.service.factory
+  if (typeof datasource === 'object' && !datasource.name) [options,datasource] = [datasource] // .to({ options })
+  else if (datasource) {
+    if (datasource._is_service_class) [ Service, datasource ] = [ datasource, datasource.name ] // .to(ServiceClass)
+    else if (datasource.name)  datasource = datasource.name // .to({ name: 'Service' }) from cds-typer
+    if (!options && datasource in cds.services) return Promise.resolve (cds.services[datasource])
+  }
+  const promise = (async()=>{
+    TRACE?.time(`cds.connect.to ${datasource}`.padEnd(22).slice(0,22))
+    const o = Service._is_service_class ? {} : options4 (datasource, options)
+    const m = await model4 (o)
+    // check if required service definition exists
+    const required = cds.requires[datasource]
+    if (required?.model?.length && datasource !== 'db' && !m.definitions[required.service||datasource]) {
+      LOG.error(`No service definition found for '${required.service || datasource}', as required by 'cds.requires.${datasource}':`, required)
+      throw new Error (`No service definition found for '${required.service || datasource}'`)
+    }
+    // construct new service instance
+    let srv = await new Service (datasource,m,o); await (Service._is_service_class ? srv.init?.() : Service.init?.(srv))
+    if (!srv.isDatabaseService && _is_queued(o)) srv = cds.queued(srv)
+    if (!options && datasource) {
+      if (datasource === 'db') cds.db = srv
+      cds.services[datasource] = srv
+    }
+    if (!o.silent) cds.emit ('connect',srv)
+    TRACE?.timeEnd(`cds.connect.to ${datasource}`.padEnd(22).slice(0,22))
+    return srv
+  })()
+  // queue parallel requests to a single promise, to avoid creating multiple services
+  if (!options && datasource) cds.services[datasource] = promise
+  return promise
+}
+
+function options4 (name, _o) {
+  if (name?.startsWith('http:')) [_o,name] = [{ url:name }]
+  const [, kind=_o?.kind, url=_o?.url ] = /^(\w+):(.*)/.exec(name) || []
+  const conf = cds.service.bindings.at(name) || cds.requires[name] || cds.requires[kind] || cds.requires.kinds[name] || cds.requires.kinds[kind]
+  const o = { kind, ...conf, ..._o }
+  if (!o.kind) o.kind = (url||conf?.credentials?.url)?.match (/\/(hcql|rest|odata)\//)?.[1]
+  if (!o.kind && !o.impl && !o.silent) throw cds.error(
+    conf ? `Configuration for 'cds.requires.${name}' lacks mandatory property 'kind' or 'impl'` :
+      name ? `Didn't find a configuration for 'cds.requires.${name}' in ${cds.root}` :
+        `Provided options object lacks mandatory property 'kind' or 'impl'`
+  )
+  if (url) o.credentials = { ...o.credentials, url }
+  return o
+}
+
+function model4 (o) {
+  if (o.model?.definitions) return o.model // got a CSN already? -> use it
+  if (cds.model) return cds.model         // use global model if available
+  if (o.model) return cds.load (o.model) // load specified model from file
+}
+
+// at least one option is truthy and none is false
+const _is_queued = o => (o.queued || o.outboxed || o.outbox) && o.queued !== false && o.outboxed !== false && o.outbox !== false

package/node_modules/@sap/cds/lib/srv/cds-serve.js

@@ -0,0 +1,84 @@
+const cds = require ('..')
+const Service = cds.service.factory
+const {serve} = cds.service.protocols
+const {init} = Service
+
+
+/** Fluent API */
+module.exports = (services, options, o = {...options}) => ({
+  from (model) { o.from = model; return this },
+  with (impl)  { o.with = impl;  return this },
+  to (prot)    { o.to   = prot;  return this },
+  at (path)    { o.at   = path;  return this },
+  in (app)     { o.app  = app;   return this },
+  then: (r,e) => _cds_serve (services,o) .then (r,e)
+})
+
+
+/**
+ * @returns { Promise<Record<string,Service>> } single or multiple services, like that:
+ * @example let { CatalogService } = await cds.serve(...) // single or many
+ *          let CatalogService = await cds.serve(...)    // single only
+ * @import Service from './cds.Service'
+ */
+async function _cds_serve (services='all', o) {
+  const TRACE = cds.log('trace'), t0 = TRACE._debug && performance.now()
+
+  if (services.service)        { Object.assign(o,services); services = o.service }
+  else if (o.service)          { o.from ??= services; services = o.service }
+  else if (is_files(services)) { o.from ??= services; services = 'all' }
+  else if (is_csn(services))   { o.from ??= services; services = 'all' }
+
+  const srvs = await _construct (services,o)
+  if (o.app) for (let srv of srvs) if (!_ignore(srv.definition)) {
+    serve (srv, o.app)
+    cds.service.providers.push (srv)
+    o.silent || cds.emit ('serving', srv) // NOTE: only for protocol-served ones (compat behaviour)
+  }
+
+  if (t0) TRACE.debug ('cds.served in'.padEnd(21),':', (performance.now()-t0).toFixed(), 'ms')
+  if (srvs.length === 1) return Object.defineProperty (o=srvs[0], o.name, {value:o})
+  return srvs.reduce ((many,s)=>{ many[s.name] = s; return many },{})
+}
+
+
+/**
+ * Constructs service instances from a model's service definitions.
+ * @param { string & typeof cds.Service } services
+ */
+async function _construct (services, o) {
+  if (services._is_service_class) // shortcut for directly passed service classes
+    return [ await init (new services (services.name, cds.model, o)) ]
+
+  // Resolve/load the model to use subsequently
+  const csn = !o.from || o.from === '*' || o.from === 'all' ? cds.model || await cds.load('*')
+    : is_csn(o.from) ? o.from : await cds.load (o.from, { silent: true })
+  const m = cds.compile.for.nodejs (csn)
+
+  // Fetch service definitions from model
+  let defs = services == 'all' ? m.services : m.services.filter (_choose(_specified(services)))
+  defs = defs.filter (d => !d['@cds.ignore'] && !d['@cds.serve.ignore']) // skip ignored ones
+  defs = defs.filter (o.mocked ? _mock_external : _skip_external) // skip externals, or mock
+
+  // Construct services, adding upfront promises to cds.services
+  return Promise.all (defs.map (d => {
+    const n = cds.requires[d.name]?.name || d.name; o.service = d.name
+    return cds.services[n] = cds.services[d.name] = new Service(n,m,o) .then(init) .then (srv => {
+      if (d.is_external) srv.mocked = true
+      if (d.name !== n) Object.defineProperty (cds.services, d.name, {value:srv})
+      if (!o.silent) cds.emit (`serving:${n}`, srv)
+      return cds.services[n] = cds.services[d.name] = srv // replacing upfront promises with real services
+    })
+  }))
+}
+
+
+const _specified = services => services.split (/\s*,\s*/).map(s => cds.requires[s]?.service || s)
+const _choose = specified => ({name:n}) => specified.some (s => s === n || n.endsWith('.'+s))
+const _ignore = d => d?.['@protocol'] === 'none' || d?.['@cds.api.ignore']
+const _mock_external = d => _skip_external(d) || !cds.requires[d.name]?.credentials
+const _skip_external = d => !d['@external'] && !d['@cds.external'] && !cds.requires[d.name]?.external
+  || (d.is_external = true, false) // tagging all external ones, and skipping them
+
+const is_files = x => Array.isArray(x) || typeof x === 'string' && (/[^\w.$]/.test(x) || /\.(cds|csn|json)$/.test(x))
+const is_csn = x => x?.definitions