The cds Facade Object

The cds facade object provides access to all Node.js APIs. It’s implemented as a global singleton, with lazy-loading of sub packages to minimize bootstrapping time and memory consumption.

const cds = require('@sap/cds')

• cds.lazified (module | object)
• cds.version → string
• cds.home → string
• cds.env → { … }
• cds.requires → { … }
• cds.app = express.Application
• cds.model = csn
• cds.services = { cds.Services }
• cds.db = cds.Service
• cds.run, …
• cds.context → cds.Event

cds.lazified (module | object)

To minimize footprint, only the facade module itself is loaded by the import above, while close to all properties and functions provided are getters, which lazy-load respective modules only on demand. For example, you can see this in cds repl:

[capire] cds repl
Welcome to cds repl v4.1.6
> cds
cds {
  ... excerpt...
  builtin: [Getter/Setter],
  resolve: [Getter/Setter],
  load: [Getter/Setter],
  parse: [Getter/Setter],
  compile: [Getter/Setter],
  connect: [Getter/Setter],
  serve: [Getter/Setter],
  server: [Getter/Setter],
  deploy: [Getter/Setter],
  version: '4.1.6',
  home: [Getter/Setter]
}

Still in repl, enter cds.builtin, and then cds again to see the effects of lazy-loading.

This is internally done using the cds.lazified methods, which turn selected properties of a given object or module into lazy getters.

cds.lazified (module) → require

Variant cds.lazified(<module>) takes a node module as an argument and returns a derived require function, which turns all requires into lazy requires upon subsequent assignment to module.exports. For example:

require = cds.lazified(module)
module.exports = {
  aStaticProperty : module.require('foo'),
  aLazyProperty : require('bar'),
}

cds.lazified (object) → object

Variant cds.lazified(<object>) turns all arrow functions with an argument named lazy into getters, as follows:

const o = cds.lazified({
  aStaticProperty : require('foo'),
  aLazyProperty : lazy => require('bar'),
})

The lazy property will essentially be replaced as follows:

const o = cds.lazified({
  aStaticProperty : require('foo'),
  get aLazyProperty() {
    let value = require('bar')
    Object.defineProperty(this,'aLazyProperty',{value,enumerable:true,writable:true})
    return value
  }
})

cds.version → string

Returns the version of the @sap/cds package from which the current instance of the cds facade module was loaded.

cds.home → string

Returns the pathname of the @sap/cds installation folder from which the current instance of the cds facade module was loaded.

cds.env → { … }

Provides access to the effective configuration of the current process, transparently from various sources, including the local package.json or .cdsrc.json, service bindings and process environments.

Learn more about cds.env

cds.requires → { … }

… is a convenience shortcut to cds.env.requires.

cds.app = express.Application

The express.js Application object constructed during bootstrapping.

Learn more about bootstrapping in cds.server.

cds.model = csn

The effective CDS model loaded during bootstrapping, which contains all service and entity definitions, including required services.

Learn more about bootstrapping in cds.server.

cds.services = { cds.Services }

A dictionary and cache of all instances of cds.Service constructed through cds.serve, or connected to by cds.connect so far.

It’s an iterable object, so you can access individual services by name:

const { CatalogService, db } = cds.services

… as well as iterate through all services:

for (let each of cds.services) ...

cds.db = cds.Service

A shortcut to cds.services.db, the primary database service connected to during bootstrapping, if any.

Learn more about bootstrapping in cds.server.

cds.run, …

If a primary database is connected (→ see cds.db), the cds facade provides shortcuts to the database service’s methods to run queries, that is:

cds.context → cds.Event

Reference to the current root event or request, which acts as invocation context, providing access to the current tenant and user information, and also constitutes the transaction boundary for automatically managed transactions.