@sap/cds 6.3.2 → 6.4.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@
 - The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Version 6.4.0 - 2022-12-15
+
+### Added
+
+- Signatures for `ql.UPSERT`
+- Runtime support for flat database UPSERTs
+- `enterprise-messaging`: Support for `@sap/cds-mtxs`
+- `persistent-outbox`: Support for parallel processing with option `parallel: true` as well as pluggable processor functions through `service.outbox.process` (beta)
+- `cds version` now also lists packages with `@cap-js/` prefix from dependencies
+- `cds.context.http` is now available for webhook-based requests
+- `cds build` for HANA migration tables now only saves model entities annotated with `@cds.persistence.journal` as `last-dev` version.
+- `cds deploy` now uses the `VCAP_SERVICES` environment variable (if set), and skips `cf` operations in this case
+
+### Changed
+
+- `.columns(…)` of both `cql.SELECT` and `cql.INSERT` give improved code completion when paired when appropriate type definitions are present
+- Status code of error messages caused by empty `not null` fields is changed from `400` to `500` on database layer. Note, that as result the error message `Value is required` in production will be replaced by `Internal server error` in the HTTP response.
+- Underscores in environment variables can now be escaped by two `__` to set keys in `cds.env`.  For example, use `CDS_FEATURES_WITH__MOCKS=...` to set `features.with_mocks`.  Note that previously, this ended up as  `features: { with_: { mocks:... }}`, so in rare cases, it might yield unexpected results.
+- `persistent-outbox`: Only programming errors lead to `process.exit()`, unrecoverable ones are only logged and their `attempts` are updated to `options.maxAttempts`
+- Global configuration of CSRF-token handling for remote services `cds.env.features.fetch_csrf` is deprecated. Instead, please use `csrf: true/false` and `csrfInBatch: true/false` in the configuration of your remote services. These options will allow to configure CSRF-token handling for each remote service separately.
+- `cds build` no longer creates `engines` entry in package.json in case none has been defined. The Node.js version matched the minimal supported version of the CDS runtime and might therefore already be outdated.
+- For streamlined MTX, `@sap/cds` now uses the custom SAP Service Manager client built into `@sap/cds-mtxs`
+- Require new package `@cap-js/graphql` for `cds compile -2 graphql`
+
+### Fixed
+
+- Type `expr` of CQN can now describe function calls
+- Added missing optional `options` parameter in signature of `cds.serve`
+- `cds deploy` handles empty result from `cf` call correctly
+- When using CQL projections with array types, the type of the projection variable will now be correctly inferred as a single element of that array
+- `cds deploy` logs without label
+- Localized draft requests with nested expand in the case of `to many` now return localized data
+- Protected service root for REST adapter
+- `cds build` logs tar error message
+- Resolve view only with renamed fields in orderBy case
+- In case of `$apply` no default values for `top` or `skip` are set in subselects
+- Environment variables like `cds.requires.<service>.kind...` now consistently override services set in e.g. `package.json`
+- Expand of composition backlink now accesses draft instance instead of active
+- Performance of server bootstrap for services with lots of entities
+- Error with virtual properties in expand combined with draft
+- req.tenant is properly propagated by custom authentication in odata and rest
+- Error with `SiblingEntity` in draft
+- Quoting of keys typed as `cds.String` in error targets. Error targets are a relative resource path to correlate error
+messages with the corresponding text input filed in the UI in an OData HTTP error response body for errors, warnings,
+and info messages. For example:
+
+```diff
+HTTP/1.1 400 Bad Request
+OData-Version: 4.0
+content-type: application/json;odata.metadata=minimal
+Connection: close
+Content-Length: 145
+
+{
+  "error": {
+    "code": "400",
+    "message": "Value is required",
+-    "target": "items(ID=string-key-1)/text",
++    "target": "items(ID='string-key-1')/text",
+    "@Common.numericSeverity": 4
+  }
+}
+```
+
+- Application crash if batched Uri uses invalid percent encoding
+- `cds build` for HANA no longer produces `hdbtabledata` for csv files that refer to non-existing entities. This can be the case for imported content packages that bring csv files for entities that are not used in the application model.
+- `cds build` for HANA now gives precedence for csv files from application layer. This is important for imported content packages that bring csv files that shall be overwritten in the application layer.
+- `cds build` for Java no longer adds the service `cds.xt.MTXServices` to the application model.
+- `cds build` no longer fails when creating large resource TAR archives for MTXS projects.
+
+### Removed
+
+- Removed `PreconditionFailedError` when sending a request with an `if-match` header on an entity without an etag
+- Check for forbidden deep operations for associations on database layer. All non key fields for associations provided by request are ignored. Please check https://cap.cloud.sap/docs/guides/providing-services#associations-vs-compositions for more information. Note that this is a breaking change for applications that rely on checks for forbidden deep operations by runtime.
+
 ## Version 6.3.2 - 2022-11-21
 
 ### Fixed
@@ -57,6 +132,7 @@
 ### Changed
 
 - In `enterprise-messaging`, emitting CloudEvents messages sets the HTTP header `Content-Type: application/cloudevents+json`
+- Added type definition for `cds.User`
 
 ### Fixed
 

package/apis/cds.d.ts

@@ -22,7 +22,7 @@ declare global {
 	const DROP: typeof cds.ql.DROP
 
 	// and these allow us to use them as type too, i.e. `const q: SELECT<Book> = ...`
-	type SELECT<T> = ql.SELECT<T>	
+	type SELECT<T> = ql.SELECT<T>
 	type INSERT<T> = ql.INSERT<T>
 	type UPDATE<T> = ql.UPDATE<T>
 	type DELETE<T> = ql.DELETE<T>

package/apis/core.d.ts

@@ -1,108 +1,136 @@
 // import types from '../lib/core'
 import { ReflectedModel, LinkedModel, LinkedDefinition } from './reflect'
-import { CSN as csn, Definition } from "./csn"
+import { CSN as csn, Definition } from './csn'
 
-export = cds
-declare class cds {
+type UserInput = string | { id: string; attr: Record<string, string>; roles: Record<string, string> } | User
 
-	/**
-	 * Turns the given plain CSN model into a linked model
-	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
-	 */
-	linked (model : csn) : LinkedModel
-
-	/**
-	 * Turns the given plain CSN model into a reflected model
-	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
-	 */
-	reflect (model : csn) : ReflectedModel
+declare class User {
+  constructor(obj?: UserInput)
+  id: string
+  /**
+   * @deprecated Use https://cap.cloud.sap/docs/node.js/events#locale instead
+   */
+  locale: string
+  /**
+   * @deprecated Use https://cap.cloud.sap/docs/node.js/events#tenant instead
+   */
+  tenant: string | undefined
+  attr: Record<string, string>
+  roles: Record<string, string>
+  static Privileged: typeof Privileged
+  is(role: string): boolean
+}
+/**
+ * Subclass for executing code with superuser privileges.
+ */
+declare class Privileged extends User {
+  constructor()
+  is(): boolean
+}
 
+export = cds
+declare class cds {
+  /**
+   * Turns the given plain CSN model into a linked model
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+   */
+  linked(model: csn): LinkedModel
 
-	// infer (query : cqn, model : csn) : LinkedDefinition
+  /**
+   * Turns the given plain CSN model into a reflected model
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+   */
+  reflect(model: csn): ReflectedModel
 
-	builtin: {
-		 /**
-			* Base classes of linked definitions from reflected models.
-			* @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-builtin-classes)
-			*/
-		classes: {
-			Association : Definition
-			Composition : Definition
-			context : Definition
-			service : Definition
-			type : Definition
-			array : Definition
-			struct : Definition
-			entity : Definition
-			event : Definition
-		},
-		types: {},
-	}
+  /**
+   * Represents the user in a given context.
+   * @see [capire docs](https://cap.cloud.sap/docs/node.js/authentication#cds-user)
+   */
+  User: typeof User
 
-	/**
-	 * Base class for linked Associations from reflected models.
-	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-	 */
-	Association : Definition
+  // infer (query : cqn, model : csn) : LinkedDefinition
 
-	/**
-	 * Base class for linked Compositions from reflected models.
-	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
-	 */
-	Composition : Definition
+  builtin: {
+    /**
+     * Base classes of linked definitions from reflected models.
+     * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-builtin-classes)
+     */
+    classes: {
+      Association: Definition
+      Composition: Definition
+      context: Definition
+      service: Definition
+      type: Definition
+      array: Definition
+      struct: Definition
+      entity: Definition
+      event: Definition
+    }
+    types: {}
+  }
 
+  /**
+   * Base class for linked Associations from reflected models.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
+   */
+  Association: Definition
 
-	/**
-	 * Base class for linked entities from reflected models.
-	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
-	 */
-	entity : Definition
+  /**
+   * Base class for linked Compositions from reflected models.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-Association)
+   */
+  Composition: Definition
 
-	struct : Definition
-	array : Definition
-	context : Definition
-	service : Definition
+  /**
+   * Base class for linked entities from reflected models.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect#cds-entity)
+   */
+  entity: Definition
 
-	/**
-	 * Add aspects to a given object, for example:
-	 *
-	 *    extend (Object.prototype) .with (class {
-	 *       get foo() { return ... }
-	 *       bar() {...}
-	 *    }.prototype)
-	 */
-	extend <T> (target:T) : ({
-		with <X,Y,Z> (x:X, y:Y, z:Z): ( T & X & Y & Z )
-		with <X,Y> (x:X, y:Y): ( T & X & Y )
-		with <X> (x:X): ( T & X )
-	})
+  struct: Definition
+  array: Definition
+  context: Definition
+  service: Definition
 
-	/**
-	 * Equip a given facade object with getters for lazy-loading modules instead
-	 * of static requires. Example:
-	 *
-	 *    const facade = lazify ({
-	 *       sub: lazy => require ('./sub-module')
-	 *    })
-	 *
-	 * The first usage of `facade.sub` will load the sub module
-	 * using standard Node.js's `module.require` functions.
-	 */
-	lazify : <T>(target:T) => T
+  /**
+   * Add aspects to a given object, for example:
+   *
+   *    extend (Object.prototype) .with (class {
+   *       get foo() { return ... }
+   *       bar() {...}
+   *    }.prototype)
+   */
+  extend<T>(target: T): {
+    with<X, Y, Z>(x: X, y: Y, z: Z): T & X & Y & Z
+    with<X, Y>(x: X, y: Y): T & X & Y
+    with<X>(x: X): T & X
+  }
 
-	/**
-	 * Prepare a node module for lazy-loading submodules instead
-	 * of static requires. Example:
-	 *
-	 *    require = lazify (module) //> turns require into a lazy one
-	 *    const facade = module.exports = {
-	 *       sub: require ('./sub-module')
-	 *    })
-	 *
-	 * The first usage of `facade.sub` will load the sub module
-	 * using standard Node.js's `module.require` functions.
-	 */
-	lazified : <T>(target:T) => T
+  /**
+   * Equip a given facade object with getters for lazy-loading modules instead
+   * of static requires. Example:
+   *
+   *    const facade = lazify ({
+   *       sub: lazy => require ('./sub-module')
+   *    })
+   *
+   * The first usage of `facade.sub` will load the sub module
+   * using standard Node.js's `module.require` functions.
+   */
+  lazify: <T>(target: T) => T
 
+  /**
+   * Prepare a node module for lazy-loading submodules instead
+   * of static requires. Example:
+   *
+   *    require = lazify (module) //> turns require into a lazy one
+   *    const facade = module.exports = {
+   *       sub: require ('./sub-module')
+   *    })
+   *
+   * The first usage of `facade.sub` will load the sub module
+   * using standard Node.js's `module.require` functions.
+   */
+  lazified: <T>(target: T) => T
 }
 // & typeof import ('../lib/index')

package/apis/cqn.d.ts

@@ -1,4 +1,4 @@
-export type Query = SELECT | INSERT | UPDATE | DELETE | CREATE | DROP
+export type Query = SELECT | INSERT | UPDATE | DELETE | CREATE | DROP | UPSERT
 export type ParsedExpr = expr & { _:string }
 
 export type SELECT = {SELECT:{
@@ -22,6 +22,14 @@ export type INSERT = {INSERT:{
 	rows : any[]
 }}
 
+export type UPSERT = {UPSERT:{
+	into : name
+	entries : any[]
+	columns : string[]
+	values : any[]
+	rows : any[]
+}}
+
 export type UPDATE = {UPDATE:{
 	entity : name
 	data : { [key:string] : expr }
@@ -47,12 +55,13 @@ export type column_expr = expr & { as?: name, cast?:any, expand?: column_expr[],
 export type predicate = _xpr
 type ordering_term = expr & { sort?: "asc"|"desc", nulls?: "first"|"last" }
 
-export type expr = ref | val | xpr | SELECT
+export type expr = ref | val | xpr | function_call | SELECT
 type ref = {ref:( name & { id?:string, where?:expr, args?:expr[] } )[]}
 type val = {val:any}
 type xpr = {xpr:_xpr}
 type _xpr = ( expr | operator ) []
 type operator = string
+type function_call = {func: string, args: {[key: string]: unknown}[]}
 
 export type enum_literal = {"#": string}
 export type expr_literal = {"=": string}

package/apis/internal/inference.d.ts

@@ -2,13 +2,18 @@
 // They are merely meant as definitions that are used
 // in several places within the API.
 
+
+export interface Constructable<T> {
+	new(...args: any[]): T
+}
+
 // any class (not value) of array to represent plural types used in cds-typer.
 // Mainly used as pattern match for SingularType
 //type ArrayConstructable = Constructable<Array<unknown>>
-export interface ArrayConstructable<T = any[]> {
+export interface ArrayConstructable<T = any> {
 	new(...args: any[]): T[]
 }
 
 // concrete singular type.
-// `SingularType<Books>` == `Book`.
+// `SingularType<typeof Books>` == `Book`.
 export type SingularType<T extends ArrayConstructable<T>> = InstanceType<T>[number]

package/apis/ql.d.ts

@@ -1,6 +1,6 @@
 import {Definition} from "./csn"
 import * as CQN from "./cqn"
-import { ArrayConstructable, SingularType } from "./internal/inference"
+import { Constructable, ArrayConstructable, SingularType } from "./internal/inference"
 
 export type Query = CQN.Query
 
@@ -8,10 +8,6 @@ export class ConstructedQuery {
 	then(_resolved:(x:any)=>any, _rejected:(e:Error)=>any) : any
 }
 
-interface Constructable<T> {
-	new(...args: any[]): T
-}
-
 export class cds_ql {
 	ql:QL<any> & ((context:object) => QL<any>)
 }
@@ -36,7 +32,12 @@ interface QLExtensions {
  */ 
 type Subqueryable <T> = ((fn:((a:T)=>any)|"*") => T)
 
-type Proxy_<T> =  {
+
+/**
+ * Wrap every attribute into a proxy that supports operations
+ * in addition to its regular capabilities.
+ */
+type ProxiedAttributes<T> =  {
 	[Key in keyof T]: Proxy<T[Key]> //& QLExtensions
 } & {
 	/**
@@ -49,15 +50,23 @@ type Proxy_<T> =  {
 	get: (path: string) => any // Proxy<unknown>
 } & QLExtensions
 
-export type Proxy<T> = (T extends Subqueryable<infer U>
-		? (Omit<T, ""> & Subqueryable<Proxy<U>>) // drop ((x: T) => T) in favour of (x: Proxy<T>) => Proxy<T>)
-		: (Proxy_<T>))
+/**
+ * Entrance type for Proxies. The conditional makes sure that we don't
+ * wrap properties into multiple layers of proxy.
+ * Proxy_ was required as we can't circularily reference a type during its definition.
+ * So `Proxy<T> = T extends Proxy<any> ...` was not possible.
+ */
+export type Proxy<T> = T extends Proxy_<any> ? T : Proxy_<T>
+
+export type Proxy_<T> = (T extends Subqueryable<infer U>
+		? (Omit<T, ""> & Subqueryable<Proxy_<U>>) // drop ((x: T) => T) in favour of (x: Proxy<T>) => Proxy<T>)
+		: (ProxiedAttributes<T>))
 	& QLExtensions
 
 // Alias for projections
 // https://cap.cloud.sap/docs/node.js/cds-ql?q=projection#projection-functions
-export type Projection<T> = (e:T)=>void
-
+//export type Projection<T> = (e:T)=>void
+export type Projection<T> = (e:Proxy<T extends ArrayConstructable ?  SingularType<T> : T>)=>void
 // Type for query pieces that can either be chained to build more complex queries or
 // awaited to materialise the result:
 // `Awaitable<SELECT<Book>, Book> = SELECT<Book> & Promise<Book>`
@@ -75,6 +84,7 @@ export type Awaitable<T, I> = T & Promise<I>
 // all the functionality of an instance of SELECT, but directly callable:
 // new SELECT(...).(...) == SELECT(...)
 export type StaticSELECT<T> = typeof SELECT
+	& ((...columns: (T extends ArrayConstructable<any> ? keyof SingularType<T> : keyof T)[]) => SELECT<T>)
 	& ((...columns:string[]) => SELECT<T>) 
 	& ((columns:string[]) => SELECT<T>)
 	& (TaggedTemplateQueryPart<SELECT<T>>)
@@ -108,6 +118,7 @@ export class SELECT<T> extends ConstructedQuery {
 	byKey (primaryKey? : PK) : this
 	columns: TaggedTemplateQueryPart<this>
 		& ((projection: Projection<T>) => this)
+		& ((...col: (T extends ArrayConstructable<any> ? keyof SingularType<T> : keyof T)[]) => this)
 		& ((...col:string[]) => this)
 	where: TaggedTemplateQueryPart<this>
 		& ((predicate:object) => this)
@@ -190,12 +201,35 @@ export class INSERT<T> extends ConstructedQuery {
 		& ((entity : Definition | string) => this)
 	data (block : (e:T)=>void) : this
 	entries (...entries : object[]) : this
+	columns (...col: (T extends ArrayConstructable<any> ? keyof SingularType<T> : keyof T)[]) : this
 	columns (...col: string[]) : this
 	values (... val: any[]) : this
 	rows (... row: any[]) : this
 	INSERT : CQN.INSERT
 }
 
+
+export class UPSERT<T> extends ConstructedQuery {
+	static into : (<T extends ArrayConstructable<any>> (entity:T, entries? : object | object[]) => UPSERT<SingularType<T>>)
+		& (TaggedTemplateQueryPart<UPSERT<unknown>>)
+		& ((entity : Definition | string, entries? : object | object[]) => UPSERT<any>)
+		& (<T> (entity:Constructable<T>, entries? : object | object[]) => UPSERT<T>)
+		& (<T> (entity:T, entries? : T | object | object[]) => UPSERT<T>)
+	
+	into: (<T extends ArrayConstructable> (entity:T) => this) 
+		& TaggedTemplateQueryPart<this> 
+		& ((entity : Definition | string) => this)
+	data (block : (e:T)=>void) : this
+	entries (...entries : object[]) : this
+	columns (...col: (T extends ArrayConstructable<any> ? keyof SingularType<T> : keyof T)[]) : this
+	columns (...col: string[]) : this
+	values (... val: any[]) : this
+	rows (... row: any[]) : this
+	UPSERT : CQN.UPSERT
+}
+
+
+
 export class DELETE<T> extends ConstructedQuery {
 	static from:
 		TaggedTemplateQueryPart<Awaitable<SELECT<unknown>, InstanceType<any>>>

package/apis/serve.d.ts

@@ -19,6 +19,13 @@ interface _fluent {
 	// (req,res) : void
 }
 
+// these are temporary types until the API has been properly typed.
+interface service_options {
+	service?: string | unknown,
+	from?: '*' | 'all' | string | unknown,
+	[key: string]: unknown
+}
+
 export = cds_serve
 declare class cds_serve {
 
@@ -26,7 +33,7 @@ declare class cds_serve {
 	 * Constructs service providers from respective service definitions
 	 * @see [capire](https://cap.cloud.sap/docs/node.js/api#cds-serve)
 	 */
-	serve (service : string) : _fluent & Promise<cds_services>
+	serve (service : string, options?: service_options) : _fluent & Promise<cds_services>
 
 	/**
 	 * The default bootstrap function as loaded from server.js