@sap/cds 7.3.0 → 7.4.0

package/apis/events.d.ts

@@ -0,0 +1,124 @@
+import { LinkedDefinition } from './linked'
+import { Query } from './cqn'
+import { ref } from './cqn'
+import * as express from "express"
+
+
+export default class cds {
+
+  /**
+   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+   */
+  EventContext: typeof EventContext
+
+  /**
+   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+   */
+  Event: typeof Event
+
+  /**
+   * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+   */
+  Request: typeof Request
+
+  /**
+   * Represents the user in a given context.
+   * @see [capire docs](https://cap.cloud.sap/docs/node.js/authentication#cds-user)
+   */
+  User: typeof User
+}
+
+
+/**
+ * Represents the invocation context of incoming request and event messages.
+ * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+ */
+export class EventContext {
+  http?: {req: express.Request, res: express.Response}
+  tenant: string
+  user: User
+  id: string
+  locale: `${string}_${string}`
+  timestamp: Date
+}
+
+/**
+ * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+ */
+export class Event extends EventContext {
+  event: string
+  data: any
+  headers: {}
+}
+
+/**
+ * @see [capire docs](https://cap.cloud.sap/docs/node.js/events)
+ */
+export class Request extends Event {
+  params: (string | {})[]
+  method: string
+  path: string
+  target: LinkedDefinition
+  /**
+   * Shortcut to {@link target.name}
+   * @see https://cap.cloud.sap/docs/node.js/events#req-entity
+   */
+  entity: string
+  query: Query
+  subject: ref
+
+  reply(results: any): void
+
+  notify(code: number, message: string, target?: string, args?: any[]): Error
+  info(code: number, message: string, target?: string, args?: any[]): Error
+  warn(code: number, message: string, target?: string, args?: any[]): Error
+  error(code: number, message: string, target?: string, args?: any[]): Error
+  reject(code: number, message: string, target?: string, args?: any[]): Error
+
+  notify(code: number, message: string, args?: any[]): Error
+  info(code: number, message: string, args?: any[]): Error
+  warn(code: number, message: string, args?: any[]): Error
+  error(code: number, message: string, args?: any[]): Error
+  reject(code: number, message: string, args?: any[]): Error
+
+  notify(message: string, target?: string, args?: any[]): Error
+  info(message: string, target?: string, args?: any[]): Error
+  warn(message: string, target?: string, args?: any[]): Error
+  error(message: string, target?: string, args?: any[]): Error
+  reject(message: string, target?: string, args?: any[]): Error
+
+  notify(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
+  info(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
+  warn(message: { code?: number | string; message: string; target?: string; args?: any[] }): Error
+  error(message: { code?: number | string; message: string; target?: string; args?: any[], status?: number }): Error
+  reject(message: { code?: number | string; message: string; target?: string; args?: any[], status?: number }): Error
+}
+
+
+export class User {
+  constructor(obj?: string | { id: string; attr: Record<string, string>; roles: Record<string, string> } | User)
+  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: Array<string> | 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
+}

package/apis/{reflect.d.ts → linked.d.ts}

@@ -1,39 +1,23 @@
-import {
-	CSN as ParsedModel,
-	Association as ParsedAssociation,
-	entity as ParsedEntity,
-	kind
-} from "./csn"
+import { CSN, FQN, Association, Definition, entity, kinds } from "./csn"
 
+export type LinkedDefinition = linked & Definition & LinkedEntity & LinkedAssociation
+export type Definitions = { [name: string]: LinkedDefinition }
 
-export type Definitions = { [name:string]: Definition }
-export type Definition = LinkedDefinition & entity & Association
-type Visitor = (def:Definition, name:string, parent:Definition, defs:Definitions) => void
-type Filter = string | ((def:Definition) => boolean)
-
-
-/**
- * Applying cds.reflect in a model ensures that all contained definitions have their `name` and `kind` filled in.
- */
-export interface LinkedDefinition {
-	is (kind: kind | 'Association' | 'Composition') : boolean
-    name : string
+export interface linked {
+	is(kind: kinds | 'Association' | 'Composition'): boolean
+	name: FQN
 }
 
-interface Association extends LinkedDefinition, ParsedAssociation {
-	is2one : boolean
-    is2many : boolean
+interface LinkedEntity extends linked, entity {
+	keys: Definitions
 }
 
-interface entity extends LinkedDefinition, ParsedEntity {
-	keys : Definitions
+interface LinkedAssociation extends linked, Association {
+	is2one: boolean
+	is2many: boolean
 }
 
-
-export interface LinkedModel extends ReflectedModel {}
-
-
-export interface ReflectedModel extends ParsedModel {
+export interface LinkedCSN extends CSN {
 
 	/**
 	 * Fetches definitions matching the given filter, returning an iterator on them.
@@ -43,13 +27,13 @@ export interface ReflectedModel extends ParsedModel {
 	 *      let entities = [...m.each('entity')]  //> capture all
 	 *      let entities = m.all('entity')          //> equivalent shortcut
 	 */
-	each (x:Filter, defs?: Definitions) : IterableIterator<LinkedDefinition>
+	each(x: Filter, defs?: Definitions): IterableIterator<any>
 
 	/**
 	 * Fetches definitions matching the given filter, returning them in an array.
 	 * Convenience shortcut for `[...reflect.each('entity')]`
 	 */
-	all (x:Filter, defs?: Definitions) : LinkedDefinition[]
+	all(x: Filter, defs?: Definitions): any[]
 
 	/**
 	 * Fetches definitions matching the given filter, returning the first match, if any.
@@ -58,19 +42,21 @@ export interface ReflectedModel extends ParsedModel {
 	 * @param {Filter} [x]  the filter
 	 * @param {Definitions} [defs]  the definitions to fetch in, default: `this.definitions`
 	 */
-	find (x:Filter, defs?: Definitions) : LinkedDefinition
+	find(x: Filter, defs?: Definitions): any
 
 	/**
 	 * Calls the visitor for each definition matching the given filter.
 	 * @see [capire](https://github.wdf.sap.corp/pages/cap/node.js/api#cds-reflect-foreach)
 	 */
-	foreach (x?:Filter, visitor?:Visitor, defs?: Definitions) : this
+	foreach(x: Filter, visitor: Visitor, defs?: Definitions): this
+	foreach(visitor: Visitor, defs?: Definitions): this
 
 	/**
 	 * Same as foreach but recursively visits each element definition
 	 * @see [capire](https://github.wdf.sap.corp/pages/cap/node.js/api#cds-reflect-foreach)
 	 */
-	forall (x?:Filter, visitor?:Visitor, defs?: Definitions) : this
+	forall(x: Filter, visitor: Visitor, defs?: Definitions): this
+	forall(visitor: Visitor, defs?: Definitions): this
 
 	/**
 	 * Fetches definitions declared as children of a given parent context or service.
@@ -82,7 +68,7 @@ export interface ReflectedModel extends ParsedModel {
 	 * @param parent  either the parent itself or its fully-qualified name
 	 * @param filter  an optional filter to apply before picking a child
 	 */
-	childrenOf (parent:LinkedDefinition|string, filter?:((def:Definition)=>boolean)) : Definitions
+	childrenOf(parent: any | string, filter?: ((def: LinkedDefinition) => boolean)): Definitions
 
 	/**
 	 * Provides convenient access to the model's top-level definitions.
@@ -98,9 +84,12 @@ export interface ReflectedModel extends ParsedModel {
 	 * const {Books,Authors} = model.exports
 	 * SELECT.from (Books) .where ({ID:11})
 	 */
-	exports : Definitions & ((namespace: string) => Definitions)
-	entities : Definitions & ((namespace: string) => Definitions)
-	services : Definitions & ((namespace: string) => Definitions)
-	definitions : Definitions
+	exports: Definitions & ((namespace: string) => Definitions)
+	entities: Definitions & ((namespace: string) => Definitions)
+	services: Definitions & ((namespace: string) => Definitions)
+	definitions: Definitions
 
 }
+
+type Visitor = (def: LinkedDefinition, name: string, parent: LinkedDefinition, defs: Definitions) => void
+type Filter = string | ((def: LinkedDefinition) => boolean)

package/apis/models.d.ts

@@ -1,9 +1,7 @@
-import { Query, expr, _xpr } from "./cqn"
+import { Query as CQN, expr, _xpr } from "./cqn"
+import { LinkedCSN } from "./linked"
 import { CSN } from "./csn"
 
-type csn = CSN
-type cqn = Query
-
 type _flavor = 'parsed' | 'xtended' | 'inferred'
 type _odata_options = {
     flavor?: 'v2' | 'v4' | 'w4'| 'x4',
@@ -29,8 +27,13 @@ type EDMX = XML
 type filename = string
 
 
-export = cds
-declare class cds {
+export default class cds {
+
+	/**
+	 * The effective CDS model loaded during bootstrapping, which contains all service and entity definitions,
+	 * including required services.
+	 */
+	model?: LinkedCSN
 
     /**
      * Provides a set of methods to parse a given model, query or expression.
@@ -38,9 +41,9 @@ declare class cds {
      */
     parse : {
         /** Shortcut to `cds.parse.cdl()` */
-        (cdl:CDL) : csn
-        cdl (cdl:CDL) : csn
-        cql (src:string) : cqn
+        (cdl:CDL) : CSN
+        cdl (cdl:CDL) : CSN
+        cql (src:string) : CQN
         expr (src:string) : expr
         xpr (src:string) : _xpr
         ref (src:string) : string[]
@@ -53,49 +56,49 @@ declare class cds {
      */
     compile : {
         /** Shortcut for `cds.compile.to.csn()` */
-        cdl (model:CDL, o?:_options) : csn,
+        cdl (model:CDL, o?:_options) : CSN,
 
         for: {
-            odata (model:csn, o?:_options) : csn
-            sql (model:csn, o?:_options) : csn
+            odata (model:CSN, o?:_options) : CSN
+            sql (model:CSN, o?:_options) : CSN
         },
         to: {
             parsed:{
-                csn (files:filename[], o?:_options) : Promise<csn>
-                csn (model:CDL, o?:_options) : csn
+                csn (files:filename[], o?:_options) : Promise<CSN>
+                csn (model:CDL, o?:_options) : CSN
             }
             xtended:{
-                csn (files:filename[], o?:_options) : Promise<csn>
-                csn (model:CDL, o?:_options) : csn
+                csn (files:filename[], o?:_options) : Promise<CSN>
+                csn (model:CDL, o?:_options) : CSN
             }
             inferred:{
-                csn (files:filename[], o?:_options) : Promise<csn>
-                csn (model:CDL, o?:_options) : csn
+                csn (files:filename[], o?:_options) : Promise<CSN>
+                csn (model:CDL, o?:_options) : CSN
             }
-            csn (files:filename[], o?:_options) : Promise<csn>
-            csn (model:CDL, o?:_options) : csn
-            yml (model:csn, o?:_options) : YAML
-            yaml (model:csn, o?:_options) : YAML
-            json (model:csn, o?:_options) : JSON
-            sql (model:csn, o?:_options) : SQL[]
-            cdl (model:csn, o?:_options) : CDL | Iterable<[CDL,{file:filename}]>
-            edm (model:csn, o?:_options|_odata_options) : EDM | string
-            edmx (model:csn, o?:_options|_odata_options) : EDMX | Iterable<[EDMX,{file:filename}]>
-            hdbcds (model:csn, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
-            hdbtable (model:csn, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
+            csn (files:filename[], o?:_options) : Promise<CSN>
+            csn (model:CDL, o?:_options) : CSN
+            yml (model:CSN, o?:_options) : YAML
+            yaml (model:CSN, o?:_options) : YAML
+            json (model:CSN, o?:_options) : JSON
+            sql (model:CSN, o?:_options) : SQL[]
+            cdl (model:CSN, o?:_options) : CDL | Iterable<[CDL,{file:filename}]>
+            edm (model:CSN, o?:_options|_odata_options) : EDM | string
+            edmx (model:CSN, o?:_options|_odata_options) : EDMX | Iterable<[EDMX,{file:filename}]>
+            hdbcds (model:CSN, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
+            hdbtable (model:CSN, o?:_options) : SQL | Iterable<[SQL,{file:filename}]>
         }
 
         /** Fluent API variant */
-        (model: csn | CDL) : {
+        (model: CSN | CDL) : {
             for: {
-                odata (o?:_options) : csn
-                sql (o?:_options) : csn
+                odata (o?:_options) : CSN
+                sql (o?:_options) : CSN
             },
             to: {
-                parsed:{ csn (o?:_options) : csn }
-                xtended:{ csn (o?:_options) : csn }
-                inferred:{ csn (o?:_options) : csn }
-                csn (o?:_options) : csn
+                parsed:{ csn (o?:_options) : CSN }
+                xtended:{ csn (o?:_options) : CSN }
+                inferred:{ csn (o?:_options) : CSN }
+                csn (o?:_options) : CSN
                 yml (o?:_options) : YAML
                 yaml (o?:_options) : YAML
                 json (o?:_options) : JSON
@@ -111,14 +114,14 @@ declare class cds {
         /** Async fluent variant reading from files */
         (files: filename[]) : {
             for: {
-                odata (o?:_options) : Promise<csn>
-                sql (o?:_options) : Promise<csn>
+                odata (o?:_options) : Promise<CSN>
+                sql (o?:_options) : Promise<CSN>
             },
             to: {
-                parsed:{ csn (o?:_options) : Promise <csn> }
-                xtended:{ csn (o?:_options) : Promise <csn> }
-                inferred:{ csn (o?:_options) : Promise <csn> }
-                csn (o?:_options) : Promise <csn>
+                parsed:{ csn (o?:_options) : Promise <CSN> }
+                xtended:{ csn (o?:_options) : Promise <CSN> }
+                inferred:{ csn (o?:_options) : Promise <CSN> }
+                csn (o?:_options) : Promise <CSN>
                 yml (o?:_options) : Promise <YAML>
                 yaml (o?:_options) : Promise <YAML>
                 json (o?:_options) : Promise <JSON>
@@ -138,18 +141,18 @@ declare class cds {
      * Essentially a shortcut for `cds.compile.to.csn(files)`
      * @param {string} files - filenames of models or if folder containing models
      */
-    get(files: '*' | filename | filename[], o?:_options) : Promise<csn>
+    get(files: '*' | filename | filename[], o?:_options) : Promise<CSN>
 
     /**
      * Shortcut for `cds.get(files, 'inferred')`
      * @param {string} files - filenames of models or if folder containing models
      */
-    load(files: '*' | filename | filename[], o?:_options) : Promise<csn>
+    load(files: '*' | filename | filename[], o?:_options) : Promise<CSN>
 
     /**
 	 * Emitted whenever a model is loaded using cds.load().
 	 */
-	on (event : 'loaded', listener : (model : csn) => void) : this
+	on (event : 'loaded', listener : (model : CSN) => void) : this
 
 
     /**
@@ -162,4 +165,16 @@ declare class cds {
      */
     resolve (files: '*' | filename | filename[]) : filename[] | undefined
 
+    	/**
+	 * Turns the given plain CSN model into a linked model
+	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+	 */
+	linked(model: CSN): LinkedCSN
+
+	/**
+	 * Turns the given plain CSN model into a reflected model
+	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-reflect)
+	 */
+	reflect(model: CSN): LinkedCSN
+
 }

package/apis/ql.d.ts

@@ -1,8 +1,7 @@
-import { Definition } from "./csn"
+import { CSN, Definition, EntityElements } from "./csn"
 import * as CQN from "./cqn"
 import { Constructable, ArrayConstructable, SingularType } from "./internal/inference"
 
-export type CQNQuery = CQN.CQNQuery
 export type Query = CQN.Query
 
 export class ConstructedQuery {
@@ -146,7 +145,7 @@ export class SELECT<T> extends ConstructedQuery {
 	static one : SELECT_one & { from: SELECT_one }
 	static distinct : typeof SELECT
     static from : SELECT_from
-	from: TaggedTemplateQueryPart<this>
+	from: SELECT_from & TaggedTemplateQueryPart<this>
 		& ((entity: Definition | string, primaryKey? : PK, projection? : Projection<unknown>) => this)
 	byKey (primaryKey? : PK) : this
 	columns: TaggedTemplateQueryPart<this>
@@ -172,8 +171,10 @@ export class SELECT<T> extends ConstructedQuery {
 	forUpdate ({wait}? : {wait?: number}) : this
 	alias (as: string) : this
 
+	elements: EntityElements
 
-// Not yet public
+
+	// Not yet public
 	// fullJoin (other: string, as: string) : this
 	// leftJoin (other: string, as: string) : this
   // 	rightJoin (other: string, as: string) : this
@@ -183,7 +184,12 @@ export class SELECT<T> extends ConstructedQuery {
 	//   & ((...expr : string[]) => this)
 	//   & ((predicate:object) => this)
 
-	SELECT : CQN.SELECT["SELECT"]
+	SELECT : CQN.SELECT["SELECT"] & {
+		forUpdate?: { wait: number }
+		forShareLock?: { wait: number }
+		search?: CQN.predicate
+		count?: boolean
+	}
 }
 
 

package/apis/{serve.d.ts → server.d.ts}

@@ -1,41 +1,50 @@
 import { Service, ServiceImpl } from "./services"
-import { LinkedDefinition } from "./reflect"
-import { csn } from "./csn"
+import { CSN } from "./csn"
 import * as http from "http"
 import { Application } from "express"
 
-// export const Service : _Service
+export default class cds {
 
-interface _fluent {
-	from (model : string | csn) : this
-	to (protocol: string) : this
-	at (path: string) : this
-	in (app: Application) : this
-	with (impl: ServiceImpl | string) : this
-	// (req,res) : void
-}
+	connect: {
+		/**
+		 * Connects to a specific datasource.
+		 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
+		 */
+		to(datasource: string, options?: cds_connect_options): Promise<Service>
 
-// these are temporary types until the API has been properly typed.
-interface service_options {
-	service?: string | unknown,
-	from?: '*' | 'all' | string | unknown,
-	[key: string]: unknown
-}
+		/**
+		 * Connects to a specific datasource via options.
+		 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect#cds-connect-to)
+		 */
+		to(options: cds_connect_options): Promise<Service>
 
-export default cds_serve
-declare class cds_serve {
+		/**
+		 * Connects the primary datasource.
+		 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-connect)
+		 */
+		(options?: string | cds_connect_options): Promise<typeof cds>  //> cds.connect(<options>)
+	}
+
+	/**
+	 * The default bootstrap function as loaded from server.js
+	 */
+	server: Function
 
 	/**
 	 * Constructs service providers from respective service definitions
 	 * @see [capire](https://cap.cloud.sap/docs/node.js/cds-serve)
 	 */
-	serve (service : string, options?: service_options) : _fluent & Promise<cds_services>
+	serve (service : string, options?: {
+		service?: string,
+		from?: '*' | 'all' | string,
+		[key: string]: unknown
+	}) : Promise<cds_services> & cds_serve_fluent
+
 
 	/**
-	 * The default bootstrap function as loaded from server.js
+	 * Emitted whenever a specific service is connected for the first time.
 	 */
-	server: cds_server
-
+	on(event: 'connect', listener: (srv: Service) => void): this
 
 
 	/**
@@ -83,21 +92,22 @@ declare class cds_serve {
 	 */
 	service : service
 
-	/**
-	 * The effective CDS model loaded during bootstrapping, which contains all service and entity definitions,
-	 * including required services.
-	 */
-	model?: csn
+  /**
+   * Provides a graceful shutdown for running servers, by first emitting `cds.emit('shutdown')`.
+   * @see [capire](https://cap.cloud.sap/docs/node.js/cds-facade#cds-exit)
+   */
+  exit(): void
 
 }
 
-export type service = LinkedDefinition & {
+export type service = any & {
 	/**
 	 * Dummy wrapper for service implementation functions.
 	 * Use that in modules to get IntelliSense.
 	 */
 	impl (impl: ServiceImpl) : typeof impl
 	impl <T> (srv:T, impl: ( this: T, srv: (T) ) => any) : typeof impl
+
 	/**
 	 * Array of all services constructed.
 	 */
@@ -105,5 +115,21 @@ export type service = LinkedDefinition & {
 }
 
 
-declare type cds_services = { [name:string]: Service }
-declare type cds_server = Function
+type cds_services = { [name:string]: Service }
+
+interface cds_serve_fluent {
+	from (model : string | CSN) : this
+	to (protocol: string) : this
+	at (path: string) : this
+	in (app: Application) : this
+	with (impl: ServiceImpl | string) : this
+	// (req,res) : void
+}
+
+interface cds_connect_options {
+	impl?: string,
+	service?: string,
+	kind?: string,
+	model?: string,
+	credentials?: object
+}