@sap/cds 6.2.3 → 6.3.0

package/lib/env/cds-env.js

@@ -1,4 +1,4 @@
-const { isfile, fs, path } = require('../utils/cds-utils')
+const { isdir, isfile, fs, path } = require('../utils/cds-utils')
 const DEFAULTS = require('./defaults'), defaults = require.resolve ('./defaults')
 const compat = require('./compat')
 const presets = require('./presets')
@@ -6,7 +6,7 @@ const serviceBindings = require('./serviceBindings');
 
 
 /**
- * Both a config inctance as well as factory for.
+ * Both a config instance as well as factory for.
  */
 class Config {
 
@@ -28,7 +28,7 @@ class Config {
   constructor (_context, _home, _defaults=true) {
     Object.assign (this, { _context, _home, _sources:[] })
 
-    // 0. determine profiles from NODE_ENV+ CDS_ENV
+    // 0. determine profiles from NODE_ENV + CDS_ENV
     const { NODE_ENV, CDS_ENV } = process.env, profiles = []
     if (NODE_ENV) profiles.push (NODE_ENV)
     if (CDS_ENV) profiles.push (...CDS_ENV.split(/\s*,\s*/))
@@ -52,29 +52,29 @@ class Config {
     const sources = Config.sources(_home, _context)
 
     // 2. read config sources in defined order
-    for (const source of sources) {
-      this._load(source.path, source.file, source.mapper, this._profiles, false)
+    for (const { path, file, mapper } of sources) {
+      this._load(path, file, mapper, this._profiles, false)
     }
 
     // 3. read important (!) profiles from config sources in defined order
     const important = new Set(this.profiles.map( profile => `${profile}!` ).filter( profile => this._profiles._defined.has( profile ) ));
     if (important.size > 0) {
-      for (const source of sources) {
-        this._load(source.path, source.file, source.mapper, important, true)
+      for (const { path, file, mapper } of sources) {
+        this._load(path, file, mapper, important, true)
       }
     }
 
-    // 4. link dependant services (through kind/use)
+    // 4. link dependent services (through kind/use)
     this._link_required_services()
 
     // 5. add process env
     this._add_process_env(_context, _home)
 
-    // 6. link dependant services again -> e.g. to allow things like CDS_requires_db=sql
+    // 6. link dependent services again -> e.g. to allow things like CDS_requires_db=sql
     this._link_required_services()
 
     // 7. complete service configurations from cloud service bindings
-    this._add_cloud_service_bindings({ VCAP_SERVICES: process.env.VCAP_SERVICES, SERVICE_BINDING_ROOT: process.env.SERVICE_BINDING_ROOT })
+    this._add_cloud_service_bindings(process.env)
 
     // 8. Add compatibility for mtx
     if (this.requires && this.requires.db) {
@@ -480,48 +480,13 @@ function _readJson (file) {
 
 
 
-function _readFromDir (p, isDir) {
-  if (typeof isDir === "undefined") {
-    try {
-      const entry = fs.statSync(p)
-      if (entry.isDirectory()) {
-        isDir = true
-      } else if (isFile(p, entry)) {
-        isDir = false
-      } else {
-        return undefined
-      }
-    } catch (e) {
-      return undefined
-    }
-  }
-  if (isDir) {
+function _readFromDir (p) {
+  if (isdir(p)) {
     const result = {}
-    const entries = fs.readdirSync(p, {withFileTypes: true})
-    for (let entry of entries) {
-      const entryPath = path.join(p, entry.name)
-      if (entry.isDirectory()) {
-        result[entry.name] = _readFromDir(entryPath, true)
-      } else if (isFile(entryPath, entry)) {
-        result[entry.name] = _readFromDir(entryPath, false)
-      }
-    }
+    for (const dirent of fs.readdirSync(p)) result[dirent] = _readFromDir(path.join(p, dirent))
     return result
-  } else {
-    return _value4(fs.readFileSync(p, "utf-8"))
-  }
-
-  function isFile(p, entry) {
-    if (entry.isFile()) return true
-    if (entry.isSymbolicLink()) {
-      // Kubernetes credentials use symlinks
-      const target = fs.realpathSync(p)
-      const targetStat = fs.statSync(target)
-
-      if (targetStat.isFile()) return true
-    }
-    return false
   }
+  return _value4(fs.readFileSync(p, "utf-8"))
 }
 
 

package/lib/env/cds-requires.js

@@ -38,6 +38,9 @@ exports = module.exports = {
 }
 
 
+const admin = [ 'cds.Subscriber', 'admin' ]
+const builder = [ 'cds.ExtensionDeveloper', 'cds.UIFlexDeveloper' ]
+
 const _authentication_strategies = {
 
   "basic-auth": {
@@ -49,12 +52,13 @@ const _authentication_strategies = {
   "mocked-auth": {
     kind: 'basic-auth',
     users: {
-      alice: { roles: ['admin', 'cds.Subscriber'] },
-      bob:   { roles: ['builder'] },
-      carol: { tenant: 't1', roles: ['admin', 'cds.Subscriber', 'cds.ExtensionDeveloper', 'cds.UIFlexDeveloper'] },
-      dave:  { tenant: 't1', roles: ['cds.Subscriber'], features: [] }, // user-specific features
-      erin:  { tenant: 't2', roles: ['admin', 'cds.Subscriber', 'cds.ExtensionDeveloper'] },
-      fred:  { tenant: 't2', roles: [], features: ['isbn'] },
+      alice: { tenant: 't1', roles: [ ...admin ] },
+      bob:   { tenant: 't1', roles: [ ...builder ] },
+      carol: { tenant: 't1', roles: [ ...admin, ...builder ] },
+      dave:  { tenant: 't1', roles: [ ...admin ], features: [] },
+      erin:  { tenant: 't2', roles: [ ...admin, ...builder ] },
+      fred:  { tenant: 't2', features: ['isbn'] },
+      me:    { tenant: 't1', features: ['*'] },
       yves:  { roles: ['internal-user'] },
       '*': true
     },
@@ -65,14 +69,16 @@ const _authentication_strategies = {
   },
   "jwt-auth": {
     strategy: 'JWT', // REVISIT: Can be removed when we switch to new auth middlewars
+    kind: 'jwt-auth',
     vcap: { label: 'xsuaa' }
   },
   "ias-auth": {
     kind: 'ias-auth',
     vcap: { label: 'identity' }
   },
-  "xsuaa": {
+  "xsuaa": { // CLARIFY why is this not -auth postfixed?
     strategy: 'xsuaa', // REVISIT: Can be removed when we switch to new auth middlewars
+    kind: 'xsuaa',
     vcap: { label: 'xsuaa' }
   },
   "dummy-auth": {

package/lib/env/defaults.js

@@ -12,6 +12,10 @@ module.exports = {
   },
 
   features: {
+    "[schevo]": {
+      schema_evolution: true,
+    },
+    schema_evolution: false,
     folders: 'fts/*', // where to find feature toggles -> switch on by default when released
     cls: major > 12 || major == 12 && minor >= 18,
     live_reload: !production,

package/lib/i18n/localize.js

@@ -10,8 +10,8 @@ module.exports = Object.assign (localize, {
 })
 
 
-function localize (model, /*with:*/ locale, aString) {
-  const _localize = bundle => localizeString (aString, bundle)
+function localize (model, /*with:*/ locale, aString, extBundle) {
+  const _localize = bundle => localizeString (aString, bundle, extBundle)
 
   const bundle = bundles4 (model, locale)
   if (Array.isArray(locale)) { // array of multiple locales
@@ -29,14 +29,14 @@ function localize (model, /*with:*/ locale, aString) {
 
 const TEXT_KEY_MARKER = 'i18n>'
 const TEXT_KEYS = /{b?i18n>([^"}]+)}/g
-function localizeString (aString, bundle) {
+function localizeString (aString, bundle, extBundle) {
   if (!bundle || !aString)  return aString
   if (typeof aString === 'object')  aString = JSON.stringify(aString, null, 2)
   // quick check for presence of any text key, to avoid expensive operation below
   if (!aString.includes(TEXT_KEY_MARKER))  return aString
   const escape = aString.startsWith('<?xml') ? escapeXmlAttr : /^[{[]/.test(aString) ? escapeJson : v=>v
   return aString.replace (TEXT_KEYS, (_, key) => {
-    const val = bundle[key]
+    const val = (extBundle && extBundle[key]) || bundle[key]
     return val ? escape(val) : key
   })
 }
@@ -155,11 +155,14 @@ function folders4 (model) {
   //   foo/node_modules/reuse-level-1/model.cds
   //   foo/node_modules/reuse-level-2/model.cds
   if (!model.$sources)  return []
-  const folders=[];  for (let src of model.$sources) {
+  const srcFolders = new Set (model.$sources.map (dirname))
+  const folders = []
+  srcFolders.forEach(src => {
     let folder = folder4 (src)
-    if (!folder || folders.includes(folder)) continue
-    folders.push(folder)  // use an array here to not screw up the folder order
-  }
+    if (folder && !folders.includes(folder)) {
+      folders.push(folder)  // use an array here to not screw up the folder order
+    }
+  })
 
   Object.defineProperty (model, '_i18nfolders', {value:folders})
   return folders.reverse()

package/lib/index.js

@@ -132,7 +132,7 @@ extend (cds.__proto__) .with (lazified ({
 const odp = Object.defineProperty, _global = (_,...pp) => pp.forEach (p => odp(global,p,{
   configurable:true, get:()=>{ let v=cds[_][p]; odp(this,p,{value:v}); return v }
 }))
-_global ('ql','SELECT','INSERT','UPDATE','DELETE','CREATE','DROP')
+_global ('ql','SELECT','INSERT','UPSERT','UPDATE','DELETE','CREATE','DROP')
 _global ('parse','CDL','CQL','CXL')
 
 // Check Node.js version

package/lib/log/cds-log.js

@@ -136,7 +136,7 @@ exports.winstonLogger = (options) => (label, level) => {
     return simple (label, level, ...args)
   },
   get json() {
-    return this._json || (this._json = require('./format/kibana'))
+    return this._json || (this._json = require('./format/cf'))
   }
 }
 
@@ -149,7 +149,7 @@ exports.winstonLogger = (options) => (label, level) => {
  *
  * @param {string} label the label to prefix to log output
  * @param {number} level the log level to enable -> 0=off, 1=error, 2=warn, 3=info, 4=debug, 5=trace
- * @param {any[]} args  the arguments passed to Logger.debug|log|info|wanr|error()
+ * @param {any[]} args  the arguments passed to Logger.debug|log|info|warn|error()
  */
 exports.format = (
   process.env.NODE_ENV === 'production' && cds.env.features.kibana_formatter ? log.formatters.json :

package/lib/log/format/cf.js

@@ -0,0 +1,16 @@
+const cds = require ('../../')
+const kibana = require('./kibana')
+
+/*
+ * extension of log formatter for kibana that additionally logs Cloud Foundry specific data
+ */
+module.exports = (module, level, ...args) => {
+  const toLog = kibana.addFields(module, level, ...args)
+
+  toLog.layer = 'cds'
+
+  // cds.context._ instead of cds.context.http because of messaging
+  toLog.tenant_subdomain = cds.context?._?.req?.authInfo?.getSubdomain()
+
+  return kibana.format(toLog)
+}

package/lib/log/format/kibana.js

@@ -6,7 +6,12 @@ const _l2l = { 1: 'error', 2: 'warn', 3: 'info', 4: 'debug', 5: 'trace' }
 /*
  * log formatter for kibana
  */
-module.exports = (module, level, ...args) => {
+module.exports = exports = (module, level, ...args) => {
+  const toLog = exports.addFields(module, level, ...args)
+  return exports.format(toLog)
+}
+
+exports.addFields = (module, level, ...args) => {
   // config
   const { user: log_user , kibana_custom_fields } = cds.env.log
 
@@ -28,7 +33,11 @@ module.exports = (module, level, ...args) => {
     const req = cds.context._ && cds.context._.req
     if (req && req.headers)
       for (const k in req.headers)
-        toLog[k.replace(/-/g, '_')] = k.match(/authorization/i) ? `${req.headers[k].split(' ')[0]} ***` : req.headers[k]
+        toLog[k.replace(/-/g, '_')] = (() => {
+          if (k.match(/authorization/i)) return `${req.headers[k].split(' ')[0]} ***`
+          if (k.match(/cookie/i)) return '***'
+          return req.headers[k]
+        })()
   }
   toLog.timestamp = new Date()
 
@@ -56,6 +65,10 @@ module.exports = (module, level, ...args) => {
     if (cf.length) toLog['#cf'] = { string: cf }
   }
 
+  return toLog
+}
+
+exports.format = toLog => {
   const getCircularReplacer = () => {
     const seen = new WeakSet()
     return (key, value) => {

package/lib/ql/INSERT.js

@@ -7,54 +7,55 @@ module.exports = class Query extends require('./Query') {
   }
 
   into (entity, ...data) {
-    this.INSERT.into = this._target_name4 (...arguments) // supporting tts
+    this[this.cmd].into = this._target_name4 (...arguments) // supporting tts
     if (data.length) this.entries(...data)
     return this
   }
 
   entries (...x) {
-    this.INSERT.entries = is_array(x[0]) ? x[0] : x
+    this[this.cmd].entries = is_array(x[0]) ? x[0] : x
     return this
   }
   columns (...x) {
-    this.INSERT.columns = is_array(x[0]) ? x[0] : x
+    this[this.cmd].columns = is_array(x[0]) ? x[0] : x
     return this
   }
   values (...x) {
-    this.INSERT.values = is_array(x[0]) ? x[0] : x
+    this[this.cmd].values = is_array(x[0]) ? x[0] : x
     return this
   }
   rows (...rows) {
     if (is_array(rows[0]) && is_array(rows[0][0])) rows = rows[0]
     if (!is_array(rows[0])) this._expected `Arguments ${{rows}} to be an array of arrays`
-    this.INSERT.rows = rows
+    this[this.cmd].rows = rows
     return this
   }
   _rows(rows, ...args) {
 
+    const INSERT = this.cmd
     if (Array.isArray(rows)) {
       // check if all the entries in the array are arrays
       if (rows.every(e => Array.isArray(e))) {
-        this.INSERT.rows = rows
+        this[INSERT].rows = rows
         // check if array contains one or multiple objects
       } else if (rows.every(e => typeof e === 'object')) {
-        this.INSERT.entries = rows
+        this[INSERT].entries = rows
         // the rows have been added as arguments
       } else if (args.length !== 0) {
         args.unshift(rows)
-        this.INSERT.rows = args
+        this[INSERT].rows = args
       } else {
-        this.INSERT.values = rows
+        this[INSERT].values = rows
       }
     } else if (typeof rows === 'object') {
-      this.INSERT.entries = rows
+      this[INSERT].entries = rows
     }
 
     return this
   }
   as (query) {
     if (!query || !query.SELECT) this._expected `${{query}} to be a CQN {SELECT} query object`
-    this.INSERT.as = query
+    this[this.cmd].as = query
     return this
   }
   valueOf() {

package/lib/ql/Query.js

@@ -5,16 +5,23 @@ class Query {
 
   constructor(_={}) { this[this.cmd] = _ }
 
+  alias (a) {
+    let _ = this[this.cmd] ;(_.from || _.into || _.entity).as = a
+    return this
+  }
+
   /** Creates a derived instance that initially inherits all properties. */
-  clone(){
-    const inherited = Object.create (this[this.cmd])
-    return {__proto__:this, [this.cmd]: inherited }
+  clone (_) {
+    const cmd = this.cmd || Object.keys(this)[0]
+    return {__proto__:this, [cmd]: {__proto__:this[cmd],..._} }
   }
 
-  flat(){
-    const flat = this[this.cmd]
-    for (let x=flat; x.__proto__;) Object.assign(flat, x = x.__proto__)
-    return new this.constructor (flat)
+  flat (q=this) {
+    let x = q.cmd || Object.keys(q)[0], y = q[x]
+    let protos = [y]; for (let o=y; o.__proto__;) protos.push (o = o.__proto__)
+    q[x] = Object.assign ({}, ...protos.reverse())
+    if (y.columns) for (let c of y.columns) if (c.SELECT) (this||Query.prototype).flat(c)
+    return q
   }
 
   /** Binds this query to be executed with the given service */

package/lib/ql/UPSERT.js

@@ -0,0 +1 @@
+module.exports = class Query extends require('./INSERT') {}

package/lib/ql/Whereable.js

@@ -43,7 +43,7 @@ class Query extends require('./Query') {
 }
 
 const predicate4 = (args, _clause) => {
-  if (args.length === 0) return; const x = args[0]
+  if (args.length === 0) return; /* else */ const x = args[0]
   if (x.raw) return parse.CXL(...args).xpr
   if (args.length === 1 && typeof x === 'object') {
     if (is_array(x)) return x
@@ -67,7 +67,11 @@ const _object_predicate = ([arg], _clause) => { // e.g. .where ({ID:4711, stock:
       continue
     }
     if (k === 'exists') {
-      pred.push(null, 'exists', ...predicate4([x],_clause))
+      pred.push(pred.length && 'and', 'exists', typeof x === 'object' ? x : { ref: x.split('.') })
+      continue
+    }
+    if (k === 'not exists') {
+      pred.push(pred.length && 'and', 'not', 'exists', typeof x === 'object' ? x : { ref: x.split('.') })
       continue
     }
     else pred.push('and', parse.expr(k))

package/lib/ql/cds-ql.js

@@ -11,12 +11,10 @@ require = path => { // eslint-disable-line no-global-assign
 }
 
 module.exports = Object.assign (_deprecated_srv_ql, { cdr: true,
-  Query, clone(q) {
-    const cmd = q.cmd || Object.keys(q)[0]
-    return {__proto__:q, [cmd]: {__proto__:q[cmd] }}
-  },
+  Query, clone: (q,_) => Query.prototype.clone.call(q,_),
   SELECT: require('./SELECT'),
   INSERT: require('./INSERT'),
+  UPSERT: require('./UPSERT'),
   UPDATE: require('./UPDATE'),
   DELETE: require('./DELETE'),
   CREATE: require('./CREATE'),

package/lib/req/request.js

@@ -38,6 +38,7 @@ class Request extends require('./event') {
     const q = this.query; if (this.query) { // IMPORTANT: Bulk queries don't have a _.query
       if (q.SELECT) return this._set ('path', _path4 (q.SELECT,'from'))
       if (q.INSERT) return this._set ('path', _path4 (q.INSERT,'into'))
+      if (q.UPSERT) return this._set ('path', _path4 (q.UPSERT,'into'))
       if (q.UPDATE) return this._set ('path', _path4 (q.UPDATE,'entity'))
       if (q.DELETE) return this._set ('path', _path4 (q.DELETE,'from'))
     }
@@ -104,6 +105,7 @@ const Http2Crud = {
 const SQL2Crud = {
   SELECT:   'READ',
   INSERT:   'CREATE',
+  UPSERT:   'UPSERT',
   UPDATE:   'UPDATE',
   DELETE:   'DELETE',
   BEGIN:    'BEGIN',

package/lib/srv/middlewares/cds-context.js

@@ -4,7 +4,7 @@ module.exports = ()=> {
 
   /** @type { import('express').Handler } */
   async function cds_context_provider (req, res, next) {
-    const ctx = new cds.EventContext
+    const ctx = {}
     ctx.http = { req, res }
     ctx.id = _id4(req)
     ctx.user = req.user

package/lib/srv/srv-dispatch.js

@@ -102,6 +102,7 @@ const _ensure_target = (srv,req) => {
     if (p) _ensure_fqn (req,'path',srv, p.startsWith('/') ? p.slice(1) : p)
     else if (q.SELECT) _ensure_fqn (q.SELECT,'from',srv)
     else if (q.INSERT) _ensure_fqn (q.INSERT,'into',srv)
+    else if (q.UPSERT) _ensure_fqn (q.UPSERT,'into',srv)
     else if (q.UPDATE) _ensure_fqn (q.UPDATE,'entity',srv)
     else if (q.DELETE) _ensure_fqn (q.DELETE,'from',srv)
   }

package/lib/srv/srv-tx.js

@@ -17,7 +17,7 @@ class NestedContext extends EventContext {
 /**
  * This is the implementation of the `srv.tx(req)` method. It constructs
  * a new Transaction as a derivate of the `srv` (i.e. {__proto__:srv})
- * @returns { Transaction & import('./srv-api') }
+ * @returns { Promise<Transaction & import('./srv-api')> }
  * @param { EventContext } ctx
  */
 function srv_tx (ctx,fn) { const srv = this
@@ -92,7 +92,7 @@ class Transaction {
 
     /*
      * srv.on('error', function (err, req) { ... })
-     * synchroneous modification of passed error only
+     * synchronous modification of passed error only
      * err is undefined if nested tx (cf. "root.before ('failed', ()=> this.rollback())")
      */
     if (err) for (const each of this._handlers._error) each.handler.call(this, err, this.context)
@@ -192,7 +192,7 @@ const _begin = async function (req) {
     return this.ready = this.__proto__.dispatch.call (this,req)
   // Protection against unintended tx.run() after root tx.commit/rollback()
   if (typeof this.ready === 'string' || !this.ready && this.context.tx._done) {
-    if (!cds_tx_protection) this.ready = this.begin() // compatibiliy to former behavior, which allowed tx.run() after commit/rollback
+    if (!cds_tx_protection) this.ready = this.begin() // compatibility to former behavior, which allowed tx.run() after commit/rollback
     else throw cds.error (
       `Transaction is ${this.ready || this.context.tx._done}, no subsequent .run allowed, without prior .begin`,
       { code: 'TRANSACTION_CLOSED' }

package/lib/utils/cds-utils.js

@@ -2,6 +2,7 @@ const cwd = process.env._original_cwd || process.cwd()
 const cds = require('../index')
 
 const ux = module.exports = exports = new class {
+  get inflect() { return super.inflect = require('./inflect') }
   get inspect() { return super.inspect = require('util').inspect }
   get uuid() { return super.uuid = require('@sap/cds-foss').uuid }
   get tar() { return super.tar = require('./tar') }
@@ -10,20 +11,50 @@ const ux = module.exports = exports = new class {
 const path = exports.path = require('path'), { dirname, extname, join, resolve, relative } = path
 const fs = exports.fs = Object.assign (ux,require('fs')) //> for compatibility
 
-exports.decodeURIComponent = s => { try { return decodeURIComponent(s) } catch { return s } }
-exports.decodeURI = s => { try { return decodeURI(s) } catch { return s } }
-
-exports.local = (file) => relative(cwd,file)
 
-exports.readdir = async function (x) {
-  const d = resolve (cds.root,x)
-  return fs.promises.readdir(d)
+/**
+ * Variant of `Object.keys()` which includes all keys inherited from the
+ * given object's prototypes.
+ */
+exports.Object_keys = o => ({
+  [Symbol.iterator]: function*(){ for (let k in o) yield k },
+  forEach(f){ let i=0; for (let k in o) f(k,i++,o) },
+  filter(f){ let i=0, r=[]; for (let k in o) f(k,i++,o) && r.push(k); return r },
+  map(f){ let i=0, r=[]; for (let k in o) r.push(f(k,i++,o)); return r },
+  some(f){ for (let k in o) if (f(k)) return true },
+  find(f){ for (let k in o) if (f(k)) return k },
+})
+
+
+/**
+ * Simple helper to always access results as arrays.
+ */
+exports.results = oa => {
+  return Array.isArray(oa) ? oa : oa != null ? [oa] : []
 }
 
-exports.stat = async function (x) {
-  const d = resolve (cds.root,x)
-  return fs.promises.stat(d)
+
+/**
+ * Should be used in data providers, i.e., db services to return single
+ * rows in response to SELECT.one queries.
+ */
+exports.chimera = oa => {
+  return Array.isArray(oa) ? oa : Object.defineProperties(oa,chimera)
 }
+const chimera = Object.getOwnPropertyDescriptors (class Chimera {
+  *[Symbol.iterator] (){ yield this }
+  forEach(f){ f(this,0,this) }
+  filter(f){ return f(this,0,this) ? [this] : [] }
+  map(f){ return [f(this,0,this)] }
+  some(f){ return f(this,0,this) }
+  find(f){ if (f(this,0,this)) return this }
+}.prototype)
+
+
+exports.decodeURIComponent = s => { try { return decodeURIComponent(s) } catch { return s } }
+exports.decodeURI = s => { try { return decodeURI(s) } catch { return s } }
+
+exports.local = (file) => relative(cwd,file)
 
 exports.exists = function exists (x) {
   if (x) {
@@ -50,6 +81,16 @@ exports.isfile = function isfile (x) {
   } catch(e){/* ignore */}
 }
 
+exports.stat = async function (x) {
+  const d = resolve (cds.root,x)
+  return fs.promises.stat(d)
+}
+
+exports.readdir = async function (x) {
+  const d = resolve (cds.root,x)
+  return fs.promises.readdir(d)
+}
+
 exports.read = async function read (file, _encoding) {
   const f = resolve (cds.root,file)
   const src = await fs.promises.readFile (f, _encoding !== 'json' && _encoding || 'utf8')
@@ -64,18 +105,37 @@ exports.write = function write (file, data, o) {
   return fs.mkdirp (dirname(f)).then (()=> fs.promises.writeFile (f,data,o))
 }
 
+exports.copy = function copy (x,y) {
+  if (arguments.length === 1) return {to:(...path) => copy(x,join(...path))}
+  const src = resolve (cds.root,x)
+  const dst = resolve (cds.root,y)
+  if (fs.promises.cp) return fs.promises.cp (src,dst,{recursive:true})
+  return fs.mkdirp (dirname(dst)) .then (async ()=>{
+    if (fs.isdir(src)) {
+      const entries = await fs.promises.readdir(src)
+      return Promise.all (entries.map (async each => {
+        const e = join (src,each)
+        const f = join (dst,each)
+        return copy (e,f)
+      }))
+    } else {
+      return fs.promises.copyFile (src,dst)
+    }
+  })
+}
+
 exports.mkdirp = async function (...path) {
   const d = resolve (cds.root,...path)
   await fs.promises.mkdir (d,{recursive:true})
   return d
 }
 
-exports.rmdir = (...path) => {
+exports.rmdir = async function (...path) {
   const d = resolve (cds.root,...path)
   return fs.promises.rm (d, {recursive:true})
 }
 
-exports.rimraf = (...path) => {
+exports.rimraf = async function (...path) {
   const d = resolve (cds.root,...path)
   return fs.promises.rm (d, {recursive:true,force:true})
 }
@@ -85,23 +145,6 @@ exports.rm = async function rm (x) {
   return fs.promises.rm(y)
 }
 
-exports.copy = async function copy (x,y) {
-  const src = resolve (cds.root,x)
-  const dst = resolve (cds.root,y)
-  if (fs.promises.cp) return fs.promises.cp (src,dst,{recursive:true})
-  await fs.mkdirp (dirname(dst))
-  if (fs.isdir(src)) {
-    const entries = await fs.promises.readdir(src)
-    return Promise.all (entries.map (async each => {
-      const e = join (src,each)
-      const f = join (dst,each)
-      return copy (e,f)
-    }))
-  } else {
-    return fs.promises.copyFile (src,dst)
-  }
-}
-
 exports.find = function find (base, patterns='*', filter=()=>true) {
   const files=[];  base = resolve (cds.root,base)
   if (typeof patterns === 'string')  patterns = patterns.split(',')
@@ -134,7 +177,9 @@ exports.find = function find (base, patterns='*', filter=()=>true) {
 }
 
 
-// internal utility to load a file through ESM or CommonJs.  TODO find a better place.
+/**
+ * Internal utility to load a file through ESM or CommonJs.  TODO find a better place.
+ */
 exports._import = id => require(id)
 if (typeof jest === 'undefined') {  // jest's ESM support is experimental: https://jestjs.io/docs/ecmascript-modules
   const { pathToFileURL } = require('url')